steerdev 0.4.27__py3-none-any.whl

steerdev_agent/cli.py

@@ -0,0 +1,2254 @@
+"""CLI interface for steerdev."""
+
+import asyncio
+import os
+from pathlib import Path
+from typing import Annotated
+
+import httpx
+import typer
+from dotenv import load_dotenv
+from rich.console import Console
+from rich.panel import Panel
+
+from steerdev_agent.config.models import SteerDevConfig
+from steerdev_agent.version import get_version
+
+console = Console()
+
+# Load environment variables from .env file in current working directory
+load_dotenv(Path.cwd() / ".env")
+
+app = typer.Typer(
+    name="steerdev",
+    help="Backend task runner for steerdev.com - orchestrates CLI coding agents",
+    no_args_is_help=True,
+)
+
+# ============================================================================
+# Tasks Command Group
+# ============================================================================
+tasks_app = typer.Typer(
+    name="tasks",
+    help="Task management commands for steerdev.com",
+    no_args_is_help=True,
+)
+app.add_typer(tasks_app)
+
+
+@tasks_app.command("next")
+def tasks_next(
+    project_id: Annotated[
+        str | None,
+        typer.Option("--project-id", "-p", help="Filter by project ID (UUID)"),
+    ] = None,
+    waves: Annotated[
+        bool,
+        typer.Option(
+            "--waves/--no-waves", help="Enable wave-aware task scheduling (default: enabled)"
+        ),
+    ] = True,
+) -> None:
+    """Get the next task to work on.
+
+    By default, returns the next task with full wave context (if waves exist).
+    Use --no-waves to get a single task without wave context.
+
+    Returns the highest priority task in order:
+    1. In Progress tasks (to continue work)
+    2. Todo tasks (to start new work)
+    3. Backlog tasks (if nothing else available)
+    """
+    from steerdev_agent.api.tasks import TasksClient, display_task, display_wave_context
+
+    with TasksClient() as client:
+        if not client.check_api_key():
+            raise typer.Exit(1)
+
+        try:
+            # Try wave-aware fetch first (if enabled)
+            if waves:
+                wave_response = client.get_next_wave(project_id=project_id)
+                if wave_response is not None:
+                    display_wave_context(wave_response)
+                    return
+
+            # Fall back to single-task
+            task = client.get_next_task(project_id=project_id)
+            if task is None:
+                console.print("[yellow]No tasks available[/yellow]")
+                raise typer.Exit(0)
+
+            display_task(task, title="Next Task")
+
+        except httpx.TimeoutException:
+            console.print("[red]Error: Request timed out[/red]")
+            raise typer.Exit(1) from None
+        except httpx.HTTPError as e:
+            console.print(f"[red]HTTP Error: {e}[/red]")
+            raise typer.Exit(1) from None
+
+
+@tasks_app.command("list")
+def tasks_list(
+    status: Annotated[
+        str | None,
+        typer.Option(
+            "--status",
+            "-s",
+            help="Filter by status (backlog, unstarted, started, completed, canceled)",
+        ),
+    ] = None,
+    project_id: Annotated[
+        str | None,
+        typer.Option("--project-id", "-p", help="Filter by project ID (UUID)"),
+    ] = None,
+    limit: Annotated[
+        int,
+        typer.Option("--limit", "-l", help="Maximum number of tasks to return"),
+    ] = 20,
+    compact: Annotated[
+        bool,
+        typer.Option("--compact", "-c", help="Show truncated IDs (8 chars) instead of full UUIDs"),
+    ] = False,
+) -> None:
+    """List tasks with optional filters."""
+    from steerdev_agent.api.tasks import TasksClient, display_task_list
+
+    with TasksClient() as client:
+        if not client.check_api_key():
+            raise typer.Exit(1)
+
+        try:
+            tasks = client.list_tasks(status=status, project_id=project_id, limit=limit)
+            display_task_list(tasks, full_ids=not compact)
+
+        except httpx.TimeoutException:
+            console.print("[red]Error: Request timed out[/red]")
+            raise typer.Exit(1) from None
+        except httpx.HTTPError as e:
+            console.print(f"[red]HTTP Error: {e}[/red]")
+            raise typer.Exit(1) from None
+
+
+@tasks_app.command("get")
+def tasks_get(
+    task_id: Annotated[
+        str,
+        typer.Argument(help="Task ID (UUID) to fetch"),
+    ],
+) -> None:
+    """Get details of a specific task by ID."""
+    from steerdev_agent.api.tasks import TasksClient, display_task
+
+    with TasksClient() as client:
+        if not client.check_api_key():
+            raise typer.Exit(1)
+
+        try:
+            task = client.get_task(task_id)
+            if task:
+                display_task(task, title="Task Details")
+            else:
+                console.print(f"[red]Task not found: {task_id}[/red]")
+                raise typer.Exit(1)
+
+        except httpx.TimeoutException:
+            console.print("[red]Error: Request timed out[/red]")
+            raise typer.Exit(1) from None
+        except httpx.HTTPError as e:
+            console.print(f"[red]HTTP Error: {e}[/red]")
+            raise typer.Exit(1) from None
+
+
+@tasks_app.command("update")
+def tasks_update(
+    task_id: Annotated[
+        str,
+        typer.Argument(help="Task ID (UUID) to update"),
+    ],
+    status: Annotated[
+        str | None,
+        typer.Option(
+            "--status",
+            "-s",
+            help="New status (backlog, unstarted, started, completed, canceled)",
+        ),
+    ] = None,
+    title: Annotated[
+        str | None,
+        typer.Option("--title", "-t", help="Update task title"),
+    ] = None,
+    prompt: Annotated[
+        str | None,
+        typer.Option("--prompt", help="Update task prompt"),
+    ] = None,
+    priority: Annotated[
+        int | None,
+        typer.Option("--priority", "-P", help="Update task priority (0-3)"),
+    ] = None,
+    result_summary: Annotated[
+        str | None,
+        typer.Option("--result", "-r", help="Result summary (for completed tasks)"),
+    ] = None,
+    error_message: Annotated[
+        str | None,
+        typer.Option("--error", "-e", help="Error message (for failed tasks)"),
+    ] = None,
+    comment: Annotated[
+        str | None,
+        typer.Option("--comment", "-c", help="Comment text (supports markdown)"),
+    ] = None,
+) -> None:
+    """Update a task's status, title, or other fields."""
+    from steerdev_agent.api.tasks import (
+        VALID_STATUSES,
+        TasksClient,
+        display_update_success,
+    )
+
+    # Validate status if provided
+    if status and status not in VALID_STATUSES:
+        console.print(
+            f"[red]Error: Invalid status '{status}'. Must be one of: {', '.join(VALID_STATUSES)}[/red]"
+        )
+        raise typer.Exit(1)
+
+    # Validate priority if provided
+    if priority is not None and (priority < 0 or priority > 3):
+        console.print("[red]Error: Priority must be between 0 and 3[/red]")
+        raise typer.Exit(1)
+
+    # Check that at least one update is specified
+    if not any(
+        [status, title, prompt, priority is not None, result_summary, error_message, comment]
+    ):
+        console.print(
+            "[yellow]No updates specified. Use --status, --title, --prompt, --priority, "
+            "--result, --error, or --comment[/yellow]"
+        )
+        raise typer.Exit(1)
+
+    with TasksClient() as client:
+        if not client.check_api_key():
+            raise typer.Exit(1)
+
+        try:
+            success = client.update_task(
+                task_id=task_id,
+                status=status,
+                title=title,
+                prompt=prompt,
+                priority=priority,
+                result_summary=result_summary,
+                error_message=error_message,
+                comment=comment,
+            )
+
+            if success:
+                display_update_success(
+                    task_id=task_id,
+                    status=status,
+                    title=title,
+                    prompt=prompt,
+                    priority=priority,
+                    result_summary=result_summary,
+                    error_message=error_message,
+                    comment=comment,
+                )
+            else:
+                raise typer.Exit(1)
+
+        except httpx.TimeoutException:
+            console.print("[red]Error: Request timed out[/red]")
+            raise typer.Exit(1) from None
+        except httpx.HTTPError as e:
+            console.print(f"[red]HTTP Error: {e}[/red]")
+            raise typer.Exit(1) from None
+
+
+@tasks_app.command("create")
+def tasks_create(
+    title: Annotated[
+        str,
+        typer.Option("--title", "-t", help="Task title (required)"),
+    ],
+    prompt: Annotated[
+        str,
+        typer.Option("--prompt", help="Task prompt/description (required)"),
+    ],
+    project_id: Annotated[
+        str | None,
+        typer.Option("--project-id", "-p", help="Project ID (UUID)"),
+    ] = None,
+    priority: Annotated[
+        int,
+        typer.Option("--priority", help="Task priority (0=low, 1=medium, 2=high, 3=urgent)"),
+    ] = 1,
+    working_directory: Annotated[
+        str | None,
+        typer.Option("--workdir", "-w", help="Working directory for the task"),
+    ] = None,
+    spec_id: Annotated[
+        str | None,
+        typer.Option("--spec-id", "-s", help="Specification ID to link this task to"),
+    ] = None,
+    cycle_id: Annotated[
+        str | None,
+        typer.Option("--cycle-id", "-c", help="Cycle ID to link this task to"),
+    ] = None,
+) -> None:
+    """Create a new task."""
+    from steerdev_agent.api.tasks import TasksClient, display_task
+
+    # Validate priority
+    if priority < 0 or priority > 3:
+        console.print("[red]Error: Priority must be between 0 and 3[/red]")
+        raise typer.Exit(1)
+
+    with TasksClient() as client:
+        if not client.check_api_key():
+            raise typer.Exit(1)
+
+        try:
+            task = client.create_task(
+                title=title,
+                prompt=prompt,
+                project_id=project_id,
+                priority=priority,
+                working_directory=working_directory,
+                spec_id=spec_id,
+                cycle_id=cycle_id,
+            )
+
+            if task:
+                display_task(task, title="Task Created")
+            else:
+                raise typer.Exit(1)
+
+        except httpx.TimeoutException:
+            console.print("[red]Error: Request timed out[/red]")
+            raise typer.Exit(1) from None
+        except httpx.HTTPError as e:
+            console.print(f"[red]HTTP Error: {e}[/red]")
+            raise typer.Exit(1) from None
+
+
+# ============================================================================
+# Hooks Command Group
+# ============================================================================
+hooks_app = typer.Typer(
+    name="hooks",
+    help="Claude Code lifecycle hooks for activity reporting",
+    no_args_is_help=True,
+)
+app.add_typer(hooks_app)
+
+
+@hooks_app.command("session-start")
+def hooks_session_start() -> None:
+    """Hook called when Claude Code session starts.
+
+    Reads JSON from stdin with session_id, transcript_path, cwd, etc.
+    Reports session_start event to SteerDev API.
+    """
+    from steerdev_agent.api.hooks import HooksClient
+
+    client = HooksClient()
+    client.session_start()
+
+
+@hooks_app.command("session-end")
+def hooks_session_end() -> None:
+    """Hook called when Claude Code session ends.
+
+    Reads JSON from stdin with session_id, reason, etc.
+    Reports session_end event to SteerDev API.
+    """
+    from steerdev_agent.api.hooks import HooksClient
+
+    client = HooksClient()
+    client.session_end()
+
+
+@hooks_app.command("agent-stop")
+def hooks_agent_stop() -> None:
+    """Hook called when main Claude Code agent stops.
+
+    Reads JSON from stdin with session_id, stop_hook_active, etc.
+    Reports agent_stopped event to SteerDev API.
+    """
+    from steerdev_agent.api.hooks import HooksClient
+
+    client = HooksClient()
+    client.agent_stop()
+
+
+@hooks_app.command("subagent-stop")
+def hooks_subagent_stop() -> None:
+    """Hook called when a Claude Code subagent stops.
+
+    Reads JSON from stdin with session_id, stop_hook_active, etc.
+    Reports subagent_stopped event to SteerDev API.
+    """
+    from steerdev_agent.api.hooks import HooksClient
+
+    client = HooksClient()
+    client.subagent_stop()
+
+
+# ============================================================================
+# Sessions Command Group
+# ============================================================================
+sessions_app = typer.Typer(
+    name="sessions",
+    help="Session management commands for tracking agent execution",
+    no_args_is_help=True,
+)
+app.add_typer(sessions_app)
+
+
+@sessions_app.command("list")
+def sessions_list(
+    project_id: Annotated[
+        str | None,
+        typer.Option("--project-id", "-p", help="Filter by project ID (UUID)"),
+    ] = None,
+    status: Annotated[
+        str | None,
+        typer.Option(
+            "--status",
+            "-s",
+            help="Filter by status (pending, running, completed, failed, cancelled)",
+        ),
+    ] = None,
+    limit: Annotated[
+        int,
+        typer.Option("--limit", "-l", help="Maximum number of sessions to return"),
+    ] = 20,
+    compact: Annotated[
+        bool,
+        typer.Option("--compact", "-c", help="Show truncated IDs instead of full UUIDs"),
+    ] = False,
+) -> None:
+    """List sessions with optional filters."""
+    from steerdev_agent.api.sessions import SessionsClient, display_session_list
+
+    async def _list_sessions() -> None:
+        async with SessionsClient() as client:
+            result = await client.list_sessions(
+                project_id=project_id,
+                status=status,
+                limit=limit,
+            )
+            if result:
+                display_session_list(result.sessions, full_ids=not compact)
+            else:
+                console.print("[yellow]Failed to fetch sessions[/yellow]")
+                raise typer.Exit(1)
+
+    try:
+        asyncio.run(_list_sessions())
+    except httpx.TimeoutException:
+        console.print("[red]Error: Request timed out[/red]")
+        raise typer.Exit(1) from None
+    except httpx.HTTPError as e:
+        console.print(f"[red]HTTP Error: {e}[/red]")
+        raise typer.Exit(1) from None
+
+
+@sessions_app.command("get")
+def sessions_get(
+    session_id: Annotated[
+        str,
+        typer.Argument(help="Session ID (UUID) to fetch"),
+    ],
+) -> None:
+    """Get details of a specific session by ID."""
+    from steerdev_agent.api.sessions import SessionsClient, display_session
+
+    async def _get_session() -> None:
+        async with SessionsClient() as client:
+            session = await client.get_session(session_id)
+            if session:
+                display_session(session, title="Session Details")
+            else:
+                console.print(f"[red]Session not found: {session_id}[/red]")
+                raise typer.Exit(1)
+
+    try:
+        asyncio.run(_get_session())
+    except httpx.TimeoutException:
+        console.print("[red]Error: Request timed out[/red]")
+        raise typer.Exit(1) from None
+    except httpx.HTTPError as e:
+        console.print(f"[red]HTTP Error: {e}[/red]")
+        raise typer.Exit(1) from None
+
+
+# ============================================================================
+# Runs Command Group (kept for backwards compatibility)
+# ============================================================================
+runs_app = typer.Typer(
+    name="runs",
+    help="Run management commands for tracking agent execution sessions",
+    no_args_is_help=True,
+)
+app.add_typer(runs_app)
+
+
+@runs_app.command("list")
+def runs_list(
+    status: Annotated[
+        str | None,
+        typer.Option(
+            "--status",
+            "-s",
+            help="Filter by status (pending, running, completed, failed, cancelled)",
+        ),
+    ] = None,
+    limit: Annotated[
+        int,
+        typer.Option("--limit", "-l", help="Maximum number of runs to return"),
+    ] = 20,
+    compact: Annotated[
+        bool,
+        typer.Option("--compact", "-c", help="Show truncated IDs instead of full UUIDs"),
+    ] = False,
+) -> None:
+    """List runs with optional filters."""
+    from steerdev_agent.api.runs import RunsClient, display_run_list
+
+    async def _list_runs() -> None:
+        async with RunsClient() as client:
+            result = await client.list_runs(status=status, limit=limit)
+            if result:
+                display_run_list(result.runs, full_ids=not compact)
+            else:
+                console.print("[yellow]Failed to fetch runs[/yellow]")
+                raise typer.Exit(1)
+
+    try:
+        asyncio.run(_list_runs())
+    except httpx.TimeoutException:
+        console.print("[red]Error: Request timed out[/red]")
+        raise typer.Exit(1) from None
+    except httpx.HTTPError as e:
+        console.print(f"[red]HTTP Error: {e}[/red]")
+        raise typer.Exit(1) from None
+
+
+@runs_app.command("get")
+def runs_get(
+    run_id: Annotated[
+        str,
+        typer.Argument(help="Run ID (UUID) to fetch"),
+    ],
+) -> None:
+    """Get details of a specific run by ID."""
+    from steerdev_agent.api.runs import RunsClient, display_run
+
+    async def _get_run() -> None:
+        async with RunsClient() as client:
+            run = await client.get_run(run_id)
+            if run:
+                display_run(run, title="Run Details")
+            else:
+                console.print(f"[red]Run not found: {run_id}[/red]")
+                raise typer.Exit(1)
+
+    try:
+        asyncio.run(_get_run())
+    except httpx.TimeoutException:
+        console.print("[red]Error: Request timed out[/red]")
+        raise typer.Exit(1) from None
+    except httpx.HTTPError as e:
+        console.print(f"[red]HTTP Error: {e}[/red]")
+        raise typer.Exit(1) from None
+
+
+@runs_app.command("active")
+def runs_active(
+    compact: Annotated[
+        bool,
+        typer.Option("--compact", "-c", help="Show truncated IDs instead of full UUIDs"),
+    ] = False,
+) -> None:
+    """List currently active runs (pending or running)."""
+    from steerdev_agent.api.runs import RunsClient, display_run_list
+
+    async def _get_active_runs() -> None:
+        async with RunsClient() as client:
+            result = await client.get_active_runs()
+            if result:
+                if result.runs:
+                    display_run_list(result.runs, full_ids=not compact)
+                    console.print(f"\n[dim]Active runs: {result.count}[/dim]")
+                else:
+                    console.print("[yellow]No active runs[/yellow]")
+            else:
+                console.print("[yellow]Failed to fetch active runs[/yellow]")
+                raise typer.Exit(1)
+
+    try:
+        asyncio.run(_get_active_runs())
+    except httpx.TimeoutException:
+        console.print("[red]Error: Request timed out[/red]")
+        raise typer.Exit(1) from None
+    except httpx.HTTPError as e:
+        console.print(f"[red]HTTP Error: {e}[/red]")
+        raise typer.Exit(1) from None
+
+
+# ============================================================================
+# Specs Command Group
+# ============================================================================
+specs_app = typer.Typer(
+    name="specs",
+    help="Specification document management commands for steerdev.com",
+    no_args_is_help=True,
+)
+app.add_typer(specs_app)
+
+
+@specs_app.command("list")
+def specs_list(
+    project_id: Annotated[
+        str | None,
+        typer.Option("--project-id", "-p", help="Filter by project ID (UUID)"),
+    ] = None,
+    status: Annotated[
+        str | None,
+        typer.Option(
+            "--status",
+            "-s",
+            help="Filter by status (draft, analyzing, clarifying, planning, ready, completed)",
+        ),
+    ] = None,
+    limit: Annotated[
+        int,
+        typer.Option("--limit", "-l", help="Maximum number of specs to return"),
+    ] = 20,
+    compact: Annotated[
+        bool,
+        typer.Option("--compact", "-c", help="Show truncated IDs instead of full UUIDs"),
+    ] = False,
+) -> None:
+    """List specification documents with optional filters."""
+    from steerdev_agent.api.specs import SpecsClient, display_spec_list
+
+    with SpecsClient() as client:
+        if not client.check_api_key():
+            raise typer.Exit(1)
+
+        try:
+            specs = client.list_specs(project_id=project_id, status=status, limit=limit)
+            display_spec_list(specs, full_ids=not compact)
+
+        except httpx.TimeoutException:
+            console.print("[red]Error: Request timed out[/red]")
+            raise typer.Exit(1) from None
+        except httpx.HTTPError as e:
+            console.print(f"[red]HTTP Error: {e}[/red]")
+            raise typer.Exit(1) from None
+
+
+@specs_app.command("get")
+def specs_get(
+    spec_id: Annotated[
+        str,
+        typer.Argument(help="Spec ID (UUID) to fetch"),
+    ],
+) -> None:
+    """Get details of a specific specification document by ID."""
+    from steerdev_agent.api.specs import SpecsClient, display_spec
+
+    with SpecsClient() as client:
+        if not client.check_api_key():
+            raise typer.Exit(1)
+
+        try:
+            spec = client.get_spec(spec_id)
+            if spec:
+                display_spec(spec, title="Spec Details")
+            else:
+                console.print(f"[red]Spec not found: {spec_id}[/red]")
+                raise typer.Exit(1)
+
+        except httpx.TimeoutException:
+            console.print("[red]Error: Request timed out[/red]")
+            raise typer.Exit(1) from None
+        except httpx.HTTPError as e:
+            console.print(f"[red]HTTP Error: {e}[/red]")
+            raise typer.Exit(1) from None
+
+
+@specs_app.command("update")
+def specs_update(
+    spec_id: Annotated[
+        str,
+        typer.Argument(help="Spec ID (UUID) to update"),
+    ],
+    content: Annotated[
+        str | None,
+        typer.Option("--content", help="New content (markdown)"),
+    ] = None,
+    status: Annotated[
+        str | None,
+        typer.Option(
+            "--status",
+            "-s",
+            help="New status (draft, analyzing, clarifying, planning, ready, completed)",
+        ),
+    ] = None,
+    title: Annotated[
+        str | None,
+        typer.Option("--title", "-t", help="New title"),
+    ] = None,
+) -> None:
+    """Update a specification document's content, status, or title."""
+    from steerdev_agent.api.specs import (
+        VALID_SPEC_STATUSES,
+        SpecsClient,
+        display_spec_update_success,
+    )
+
+    # Validate status if provided
+    if status and status not in VALID_SPEC_STATUSES:
+        console.print(
+            f"[red]Error: Invalid status '{status}'. "
+            f"Must be one of: {', '.join(VALID_SPEC_STATUSES)}[/red]"
+        )
+        raise typer.Exit(1)
+
+    # Check that at least one update is specified
+    if not any([content, status, title]):
+        console.print("[yellow]No updates specified. Use --content, --status, or --title[/yellow]")
+        raise typer.Exit(1)
+
+    with SpecsClient() as client:
+        if not client.check_api_key():
+            raise typer.Exit(1)
+
+        try:
+            success = client.update_spec(
+                spec_id=spec_id,
+                content=content,
+                status=status,
+                title=title,
+            )
+
+            if success:
+                display_spec_update_success(spec_id, content, status, title)
+            else:
+                raise typer.Exit(1)
+
+        except httpx.TimeoutException:
+            console.print("[red]Error: Request timed out[/red]")
+            raise typer.Exit(1) from None
+        except httpx.HTTPError as e:
+            console.print(f"[red]HTTP Error: {e}[/red]")
+            raise typer.Exit(1) from None
+
+
+@specs_app.command("create")
+def specs_create(
+    title: Annotated[
+        str,
+        typer.Option("--title", "-t", help="Spec title (required)"),
+    ],
+    content: Annotated[
+        str,
+        typer.Option("--content", help="Spec content in markdown (required)"),
+    ],
+    project_id: Annotated[
+        str | None,
+        typer.Option("--project-id", "-p", help="Project ID (UUID)"),
+    ] = None,
+    source: Annotated[
+        str,
+        typer.Option("--source", "-s", help="Source of the spec"),
+    ] = "agent",
+) -> None:
+    """Create a new specification document."""
+    from steerdev_agent.api.specs import SpecsClient, display_spec
+
+    with SpecsClient() as client:
+        if not client.check_api_key():
+            raise typer.Exit(1)
+
+        try:
+            spec = client.create_spec(
+                title=title,
+                content=content,
+                project_id=project_id,
+                source=source,
+            )
+
+            if spec:
+                display_spec(spec, title="Spec Created")
+            else:
+                raise typer.Exit(1)
+
+        except httpx.TimeoutException:
+            console.print("[red]Error: Request timed out[/red]")
+            raise typer.Exit(1) from None
+        except httpx.HTTPError as e:
+            console.print(f"[red]HTTP Error: {e}[/red]")
+            raise typer.Exit(1) from None
+
+
+# ============================================================================
+# Context Command Group
+# ============================================================================
+context_app = typer.Typer(
+    name="context",
+    help="Project context commands for steerdev.com",
+    no_args_is_help=True,
+)
+app.add_typer(context_app)
+
+
+@context_app.command("get")
+def context_get(
+    project_id: Annotated[
+        str | None,
+        typer.Option("--project-id", "-p", help="Project ID (UUID)"),
+    ] = None,
+    format: Annotated[
+        str,
+        typer.Option(
+            "--format",
+            "-f",
+            help="Output format: json (structured) or markdown (agent-ready)",
+        ),
+    ] = "json",
+) -> None:
+    """Get project context (tech stack, patterns, structure).
+
+    Returns codebase context including:
+    - Tech stack (framework, database, auth, styling)
+    - Code patterns and conventions
+    - Directory structure
+    - AI-generated summary
+
+    Use --format markdown to get agent-ready context.
+    """
+    from steerdev_agent.api.context import ContextClient, display_context
+
+    with ContextClient() as client:
+        if not client.check_api_key():
+            raise typer.Exit(1)
+
+        try:
+            context = client.get_context(project_id=project_id, format=format)
+            if context:
+                if format == "markdown":
+                    # Print raw markdown for agent consumption
+                    console.print(context)
+                else:
+                    display_context(context)
+            else:
+                raise typer.Exit(1)
+
+        except httpx.TimeoutException:
+            console.print("[red]Error: Request timed out[/red]")
+            raise typer.Exit(1) from None
+        except httpx.HTTPError as e:
+            console.print(f"[red]HTTP Error: {e}[/red]")
+            raise typer.Exit(1) from None
+
+
+@context_app.command("refresh")
+def context_refresh(
+    project_id: Annotated[
+        str | None,
+        typer.Option("--project-id", "-p", help="Project ID (UUID)"),
+    ] = None,
+    force: Annotated[
+        bool,
+        typer.Option("--force", "-F", help="Force re-analysis even if context is up to date"),
+    ] = False,
+) -> None:
+    """Force refresh of cached project context.
+
+    Triggers a re-analysis of the project's GitHub repositories
+    to update the cached codebase context.
+
+    This analyzes:
+    - package.json/pyproject.toml for dependencies
+    - Directory structure for patterns
+    - Config files for tech stack detection
+    """
+    from steerdev_agent.api.context import (
+        ContextClient,
+        display_context_refresh_success,
+    )
+
+    with ContextClient() as client:
+        if not client.check_api_key():
+            raise typer.Exit(1)
+
+        try:
+            result = client.refresh_context(project_id=project_id, force=force)
+            if result:
+                # Show analysis results
+                analyzed = result.get("analyzed", [])
+                skipped = result.get("skipped", [])
+
+                if analyzed:
+                    console.print("[green]Analyzed:[/green]")
+                    for repo in analyzed:
+                        status = repo.get("status", "unknown")
+                        name = repo.get("full_name", repo.get("repo_name", "unknown"))
+                        if status == "completed":
+                            console.print(f"  [green]✓[/green] {name}")
+                        else:
+                            error = repo.get("error", "")
+                            console.print(f"  [red]✗[/red] {name}: {error}")
+
+                if skipped:
+                    console.print("[yellow]Skipped (up to date):[/yellow]")
+                    for repo in skipped:
+                        name = repo.get("full_name", repo.get("repo_name", "unknown"))
+                        console.print(f"  [dim]○[/dim] {name}")
+
+                pid = result.get("project_id") or project_id or "unknown"
+                display_context_refresh_success(pid)
+            else:
+                raise typer.Exit(1)
+
+        except httpx.TimeoutException:
+            console.print("[red]Error: Request timed out[/red]")
+            raise typer.Exit(1) from None
+        except httpx.HTTPError as e:
+            console.print(f"[red]HTTP Error: {e}[/red]")
+            raise typer.Exit(1) from None
+
+
+# ============================================================================
+# Activity Command Group
+# ============================================================================
+activity_app = typer.Typer(
+    name="activity",
+    help="Activity reporting commands for self-reporting progress and querying history",
+    no_args_is_help=True,
+)
+app.add_typer(activity_app)
+
+
+@activity_app.command("report")
+def activity_report(
+    event_type: Annotated[
+        str,
+        typer.Option(
+            "--type",
+            "-t",
+            help="Event type (progress, blocker, question, milestone, error, warning, info)",
+        ),
+    ],
+    message: Annotated[
+        str,
+        typer.Option("--message", "-m", help="Human-readable message describing the event"),
+    ],
+    metadata: Annotated[
+        str | None,
+        typer.Option(
+            "--metadata",
+            help='Additional metadata as JSON string (e.g., \'{"key": "value"}\')',
+        ),
+    ] = None,
+    run_id: Annotated[
+        str | None,
+        typer.Option("--run-id", "-r", help="Run ID to associate with"),
+    ] = None,
+    session_name: Annotated[
+        str | None,
+        typer.Option("--session", "-s", help="Session name"),
+    ] = None,
+) -> None:
+    """Self-report progress, blockers, or other activity events.
+
+    Use this to report your current status to the platform:
+    - progress: Report progress on a task
+    - blocker: Report something blocking progress
+    - question: Report a question or need for clarification
+    - milestone: Report reaching a milestone
+    - error: Report an error encountered
+    - warning: Report a warning or heads-up
+    - info: Report general information
+    """
+    import json as json_module
+
+    from steerdev_agent.api.activity import (
+        VALID_EVENT_TYPES,
+        ActivityClient,
+        display_report_success,
+    )
+
+    # Validate event type
+    if event_type not in VALID_EVENT_TYPES:
+        console.print(
+            f"[red]Error: Invalid event type '{event_type}'. "
+            f"Must be one of: {', '.join(VALID_EVENT_TYPES)}[/red]"
+        )
+        raise typer.Exit(1)
+
+    # Parse metadata if provided
+    metadata_dict = None
+    if metadata:
+        try:
+            metadata_dict = json_module.loads(metadata)
+        except json_module.JSONDecodeError as e:
+            console.print(f"[red]Error: Invalid JSON in metadata: {e}[/red]")
+            raise typer.Exit(1) from None
+
+    with ActivityClient() as client:
+        if not client.check_api_key():
+            raise typer.Exit(1)
+
+        try:
+            success = client.report(
+                event_type=event_type,
+                message=message,
+                metadata=metadata_dict,
+                run_id=run_id,
+                session_name=session_name,
+            )
+
+            if success:
+                display_report_success(event_type, message)
+            else:
+                raise typer.Exit(1)
+
+        except httpx.TimeoutException:
+            console.print("[red]Error: Request timed out[/red]")
+            raise typer.Exit(1) from None
+        except httpx.HTTPError as e:
+            console.print(f"[red]HTTP Error: {e}[/red]")
+            raise typer.Exit(1) from None
+
+
+@activity_app.command("query")
+def activity_query(
+    run_id: Annotated[
+        str | None,
+        typer.Option("--run-id", "-r", help="Filter by run ID"),
+    ] = None,
+    event_type: Annotated[
+        str | None,
+        typer.Option("--type", "-t", help="Filter by event type"),
+    ] = None,
+    limit: Annotated[
+        int,
+        typer.Option("--limit", "-l", help="Maximum number of events to return"),
+    ] = 20,
+) -> None:
+    """Query activity history with optional filters.
+
+    Returns recent activity events, optionally filtered by run ID or event type.
+    """
+    from steerdev_agent.api.activity import ActivityClient, display_activity_list
+
+    with ActivityClient() as client:
+        if not client.check_api_key():
+            raise typer.Exit(1)
+
+        try:
+            events = client.query(
+                run_id=run_id,
+                event_type=event_type,
+                limit=limit,
+            )
+            display_activity_list(events)
+
+        except httpx.TimeoutException:
+            console.print("[red]Error: Request timed out[/red]")
+            raise typer.Exit(1) from None
+        except httpx.HTTPError as e:
+            console.print(f"[red]HTTP Error: {e}[/red]")
+            raise typer.Exit(1) from None
+
+
+# ============================================================================
+# Git Workflow Command Group
+# ============================================================================
+git_app = typer.Typer(
+    name="git",
+    help="Git workflow commands with steerdev conventions",
+    no_args_is_help=True,
+)
+app.add_typer(git_app)
+
+
+@git_app.command("branch")
+def git_branch(
+    task_id: Annotated[
+        str | None,
+        typer.Argument(help="Task ID to create branch for (uses first 8 chars)"),
+    ] = None,
+    name: Annotated[
+        str | None,
+        typer.Option("--name", "-n", help="Custom branch name suffix"),
+    ] = None,
+) -> None:
+    """Create a task branch with steerdev naming convention.
+
+    Creates a branch named `task/<task-id-short>` or `task/<task-id-short>-<name>`.
+    Uses the first 8 characters of the task ID for the branch name.
+
+    Example:
+        steerdev git branch abc12345-...
+        # Creates: task/abc12345
+
+        steerdev git branch abc12345-... --name auth-flow
+        # Creates: task/abc12345-auth-flow
+    """
+    import subprocess
+
+    if not task_id:
+        console.print("[red]Error: Task ID is required[/red]")
+        raise typer.Exit(1)
+
+    # Use first 8 chars of task ID
+    short_id = task_id[:8]
+    branch_name = f"task/{short_id}"
+    if name:
+        branch_name = f"task/{short_id}-{name}"
+
+    try:
+        # Check if branch already exists
+        result = subprocess.run(
+            ["git", "rev-parse", "--verify", branch_name],
+            capture_output=True,
+            text=True,
+        )
+
+        if result.returncode == 0:
+            console.print(f"[yellow]Branch '{branch_name}' already exists[/yellow]")
+            # Switch to the branch
+            subprocess.run(["git", "checkout", branch_name], check=True)
+            console.print(f"[green]Switched to branch '{branch_name}'[/green]")
+        else:
+            # Create and switch to new branch
+            subprocess.run(["git", "checkout", "-b", branch_name], check=True)
+            console.print(
+                Panel(
+                    f"[bold green]Branch created[/bold green]\n\n"
+                    f"Branch: {branch_name}\n"
+                    f"Task ID: {task_id}",
+                    title="Success",
+                    border_style="green",
+                )
+            )
+
+    except subprocess.CalledProcessError as e:
+        console.print(f"[red]Git error: {e}[/red]")
+        raise typer.Exit(1) from None
+    except FileNotFoundError:
+        console.print("[red]Error: git not found. Make sure git is installed.[/red]")
+        raise typer.Exit(1) from None
+
+
+@git_app.command("pr")
+def git_pr(
+    title: Annotated[
+        str,
+        typer.Option("--title", "-t", help="PR title"),
+    ],
+    body: Annotated[
+        str | None,
+        typer.Option("--body", "-b", help="PR body/description"),
+    ] = None,
+    task_id: Annotated[
+        str | None,
+        typer.Option("--task-id", help="Task ID to reference in PR"),
+    ] = None,
+    draft: Annotated[
+        bool,
+        typer.Option("--draft", "-d", help="Create as draft PR"),
+    ] = False,
+) -> None:
+    """Create a pull request with steerdev conventions.
+
+    Uses GitHub CLI (gh) to create a PR. Automatically includes
+    task reference if task_id is provided.
+
+    Example:
+        steerdev git pr --title "Add auth" --body "Implements JWT auth"
+        steerdev git pr --title "Add auth" --task-id abc123...
+    """
+    import subprocess
+
+    # Build PR body
+    pr_body = body or ""
+    if task_id:
+        task_ref = f"\n\n## Task Reference\nTask ID: {task_id}"
+        pr_body += task_ref
+
+    # Add steerdev signature
+    pr_body += "\n\n---\nCreated with [steerdev](https://steerdev.com)"
+
+    try:
+        # Build the gh pr create command
+        cmd = ["gh", "pr", "create", "--title", title, "--body", pr_body]
+        if draft:
+            cmd.append("--draft")
+
+        result = subprocess.run(cmd, capture_output=True, text=True)
+
+        if result.returncode != 0:
+            console.print(f"[red]Error creating PR: {result.stderr}[/red]")
+            raise typer.Exit(1)
+
+        # Extract PR URL from output
+        pr_url = result.stdout.strip()
+        console.print(
+            Panel(
+                f"[bold green]Pull request created[/bold green]\n\nTitle: {title}\nURL: {pr_url}",
+                title="Success",
+                border_style="green",
+            )
+        )
+
+    except FileNotFoundError:
+        console.print("[red]Error: gh not found. Install GitHub CLI: https://cli.github.com[/red]")
+        raise typer.Exit(1) from None
+
+
+@git_app.command("status")
+def git_status() -> None:
+    """Show current branch and task context.
+
+    Displays the current git branch and extracts task ID if the branch
+    follows the task/<id> naming convention.
+    """
+    import subprocess
+
+    try:
+        # Get current branch
+        result = subprocess.run(
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        current_branch = result.stdout.strip()
+
+        # Get status summary
+        status_result = subprocess.run(
+            ["git", "status", "--short"],
+            capture_output=True,
+            text=True,
+        )
+        status_lines = (
+            status_result.stdout.strip().split("\n") if status_result.stdout.strip() else []
+        )
+        changes_count = len(status_lines)
+
+        # Extract task ID if branch follows convention
+        task_id = None
+        if current_branch.startswith("task/"):
+            # Extract the task ID part (everything after "task/")
+            task_part = current_branch[5:]  # Remove "task/" prefix
+            # Task ID is the first part before any hyphen (if name suffix was used)
+            task_id = task_part.split("-")[0] if "-" in task_part else task_part
+
+        # Build info display
+        info_lines = [
+            f"[bold cyan]Branch:[/bold cyan] {current_branch}",
+        ]
+
+        if task_id:
+            info_lines.append(f"[bold cyan]Task ID:[/bold cyan] {task_id}")
+
+        if changes_count > 0:
+            info_lines.append(
+                f"[bold cyan]Uncommitted changes:[/bold cyan] {changes_count} file(s)"
+            )
+        else:
+            info_lines.append("[bold cyan]Uncommitted changes:[/bold cyan] None")
+
+        # Check if branch is pushed
+        tracking_result = subprocess.run(
+            ["git", "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"],
+            capture_output=True,
+            text=True,
+        )
+
+        if tracking_result.returncode == 0:
+            upstream = tracking_result.stdout.strip()
+            info_lines.append(f"[bold cyan]Tracking:[/bold cyan] {upstream}")
+
+            # Check ahead/behind
+            ahead_behind = subprocess.run(
+                ["git", "rev-list", "--left-right", "--count", f"{upstream}...HEAD"],
+                capture_output=True,
+                text=True,
+            )
+            if ahead_behind.returncode == 0:
+                parts = ahead_behind.stdout.strip().split()
+                if len(parts) == 2:
+                    behind, ahead = parts
+                    if int(ahead) > 0 or int(behind) > 0:
+                        info_lines.append(
+                            f"[bold cyan]Status:[/bold cyan] {ahead} ahead, {behind} behind"
+                        )
+        else:
+            info_lines.append("[bold cyan]Tracking:[/bold cyan] Not pushed to remote")
+
+        console.print(
+            Panel(
+                "\n".join(info_lines),
+                title="Git Status",
+                border_style="blue",
+            )
+        )
+
+    except subprocess.CalledProcessError as e:
+        console.print(f"[red]Git error: {e}[/red]")
+        raise typer.Exit(1) from None
+    except FileNotFoundError:
+        console.print("[red]Error: git not found. Make sure git is installed.[/red]")
+        raise typer.Exit(1) from None
+
+
+def version_callback(value: bool) -> None:
+    """Print version and exit."""
+    if value:
+        console.print(f"steerdev version {get_version()}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-v",
+            help="Show version and exit",
+            callback=version_callback,
+            is_eager=True,
+        ),
+    ] = False,
+    config_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--config",
+            "-C",
+            help="Path to config file (default: steerdev.yaml)",
+        ),
+    ] = None,
+) -> None:
+    """SteerDev Agent - orchestrates CLI coding agents with activity reporting."""
+    # Load config file
+    config_path = config_file or Path.cwd() / "steerdev.yaml"
+    if config_path.exists():
+        try:
+            ctx.obj = SteerDevConfig.from_yaml(config_path)
+        except Exception as e:
+            console.print(f"[yellow]Warning: Failed to load config {config_path}: {e}[/yellow]")
+            ctx.obj = SteerDevConfig()
+    else:
+        ctx.obj = SteerDevConfig()
+
+
+@app.command()
+def run(
+    ctx: typer.Context,
+    project_id: Annotated[
+        str | None,
+        typer.Option(
+            "--project-id",
+            "-p",
+            help="SteerDev project ID",
+            envvar="STEERDEV_PROJECT_ID",
+        ),
+    ] = None,
+    task_id: Annotated[
+        str | None,
+        typer.Option(
+            "--task-id",
+            "-t",
+            help="Specific task ID to run (optional, fetches next task if not provided)",
+        ),
+    ] = None,
+    working_dir: Annotated[
+        Path | None,
+        typer.Option(
+            "--workdir",
+            "-w",
+            help="Working directory for the agent (defaults to current directory)",
+            exists=True,
+            file_okay=False,
+            dir_okay=True,
+        ),
+    ] = None,
+    agent_name: Annotated[
+        str | None,
+        typer.Option(
+            "--agent-name",
+            "-n",
+            help="Agent name for session tracking (reads from STEERDEV_AGENT_NAME env var)",
+            envvar="STEERDEV_AGENT_NAME",
+        ),
+    ] = None,
+    model: Annotated[
+        str | None,
+        typer.Option(
+            "--model",
+            "-m",
+            help="Model to use (e.g., claude-sonnet-4-20250514)",
+        ),
+    ] = None,
+    max_turns: Annotated[
+        int | None,
+        typer.Option(
+            "--max-turns",
+            help="Maximum number of agent turns per task",
+        ),
+    ] = None,
+    max_tasks: Annotated[
+        int,
+        typer.Option(
+            "--max-tasks",
+            help="Maximum number of tasks to process (default: 1, use 0 for unlimited)",
+        ),
+    ] = 1,
+    timeout: Annotated[
+        int | None,
+        typer.Option(
+            "--timeout",
+            help="Timeout in seconds (default: from config or 3600)",
+        ),
+    ] = None,
+    api_key: Annotated[
+        str | None,
+        typer.Option(
+            "--key",
+            "-k",
+            help="API key for steerdev.com (overrides STEERDEV_API_KEY env var)",
+            envvar="STEERDEV_API_KEY",
+        ),
+    ] = None,
+    worktrees: Annotated[
+        bool | None,
+        typer.Option(
+            "--worktrees/--no-worktrees",
+            "-W",
+            help="Enable git worktree isolation (default: from config or disabled)",
+        ),
+    ] = None,
+    dry_run: Annotated[
+        bool,
+        typer.Option(
+            "--dry",
+            help="Print the command that would be run without executing it",
+        ),
+    ] = False,
+    workflow_id: Annotated[
+        str | None,
+        typer.Option(
+            "--workflow-id",
+            help="Workflow ID for multi-phase execution (overrides config)",
+        ),
+    ] = None,
+) -> None:
+    """Run the agent for a project!
+
+    Fetches the next available task (or a specific task if --task-id is provided)
+    and executes it using Claude Code.
+
+    Configuration values are loaded from steerdev.yaml (if present) and can
+    be overridden by CLI options. Priority: CLI > env var > config file > default.
+
+    Example:
+        steerdev run --project-id abc123
+        steerdev run --project-id abc123 --task-id def456
+        steerdev run --project-id abc123 --worktrees
+        steerdev run --project-id abc123 --workflow-id wf-abc123
+        steerdev run --project-id abc123 --agent-name my-dev-agent
+        steerdev run --config custom.yaml --project-id abc123
+    """
+    from steerdev_agent.runner import run_agent
+
+    # Get config from context (loaded in app callback)
+    config: SteerDevConfig = ctx.obj or SteerDevConfig()
+
+    # Resolve project_id: CLI > env (handled by typer) > config env var
+    resolved_project_id = project_id
+    if not resolved_project_id:
+        # Try config's specified env var
+        resolved_project_id = os.environ.get(config.api.project_id_env)
+    if not resolved_project_id:
+        console.print("[red]Error: --project-id required (or set via env/config)[/red]")
+        raise typer.Exit(1)
+
+    # Resolve other options: CLI > config > hardcoded default
+    resolved_model = model if model is not None else config.agent.model
+    resolved_max_turns = max_turns if max_turns is not None else config.agent.max_turns
+    resolved_timeout = timeout if timeout is not None else config.agent.timeout_seconds
+    resolved_workflow_id = workflow_id if workflow_id is not None else config.agent.workflow_id
+    resolved_worktrees = worktrees if worktrees is not None else config.worktrees.enabled
+
+    # API key: CLI > env (via envvar) > config env var
+    resolved_api_key = api_key
+    if not resolved_api_key:
+        resolved_api_key = os.environ.get(config.api.api_key_env)
+
+    worktree_status = "enabled" if resolved_worktrees else "disabled"
+    dry_run_status = "enabled" if dry_run else "disabled"
+    max_tasks_display = "unlimited" if max_tasks == 0 else str(max_tasks)
+    workflow_status = resolved_workflow_id or "single-phase"
+    agent_name_display = agent_name or "(auto from env)"
+
+    console.print(
+        Panel(
+            f"[bold blue]SteerDev Agent[/bold blue]\n"
+            f"Project ID: {resolved_project_id}\n"
+            f"Agent Name: {agent_name_display}\n"
+            f"Task ID: {task_id or 'auto (next available)'}\n"
+            f"Working Directory: {working_dir or 'current'}\n"
+            f"Model: {resolved_model or 'default'}\n"
+            f"Max Tasks: {max_tasks_display}\n"
+            f"Timeout: {resolved_timeout}s\n"
+            f"Workflow: {workflow_status}\n"
+            f"Worktrees: {worktree_status}\n"
+            f"Dry Run: {dry_run_status}",
+            title="Starting",
+        )
+    )
+
+    # Check if shared settings are stale
+    _check_sync_staleness(working_dir or Path.cwd())
+
+    try:
+        result = asyncio.run(
+            run_agent(
+                project_id=resolved_project_id,
+                task_id=task_id,
+                working_directory=str(working_dir) if working_dir else None,
+                api_key=resolved_api_key,
+                agent_name=agent_name,
+                model=resolved_model,
+                max_turns=resolved_max_turns,
+                max_tasks=max_tasks,
+                timeout_seconds=resolved_timeout,
+                enable_worktrees=resolved_worktrees,
+                workflow_id=resolved_workflow_id,
+                dry_run=dry_run,
+            )
+        )
+
+        console.print(
+            Panel(
+                f"[bold green]Run completed[/bold green]\n"
+                f"Run ID: {result['run_id']}\n"
+                f"Duration: {result.get('duration_seconds', 0):.1f}s\n"
+                f"Tasks Executed: {result.get('tasks_executed', 0)}\n"
+                f"Succeeded: {result.get('tasks_succeeded', 0)}\n"
+                f"Failed: {result.get('tasks_failed', 0)}\n"
+                f"Events Sent: {result.get('events_sent', 0)}",
+                title="Complete",
+            )
+        )
+
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Interrupted by user[/yellow]")
+        raise typer.Exit(130) from None
+    except Exception as e:
+        console.print(f"\n[red]Error: {e}[/red]")
+        raise typer.Exit(1) from e
+
+
+@app.command()
+def daemon(
+    ctx: typer.Context,
+    project_id: Annotated[
+        str | None,
+        typer.Option(
+            "--project-id",
+            "-p",
+            help="SteerDev project ID",
+            envvar="STEERDEV_PROJECT_ID",
+        ),
+    ] = None,
+    agent_name: Annotated[
+        str | None,
+        typer.Option(
+            "--agent-name",
+            "-n",
+            help="Agent name (required, reads from STEERDEV_AGENT_NAME env var)",
+            envvar="STEERDEV_AGENT_NAME",
+        ),
+    ] = None,
+    working_dir: Annotated[
+        Path | None,
+        typer.Option(
+            "--workdir",
+            "-w",
+            help="Working directory for the agent (defaults to current directory)",
+            exists=True,
+            file_okay=False,
+            dir_okay=True,
+        ),
+    ] = None,
+    model: Annotated[
+        str | None,
+        typer.Option(
+            "--model",
+            "-m",
+            help="Model to use (e.g., claude-sonnet-4-20250514)",
+        ),
+    ] = None,
+    max_turns: Annotated[
+        int | None,
+        typer.Option(
+            "--max-turns",
+            help="Maximum number of agent turns per command/task",
+        ),
+    ] = None,
+    poll_interval: Annotated[
+        float | None,
+        typer.Option(
+            "--poll-interval",
+            help="Seconds between command queue polls (default: from config or 5.0)",
+        ),
+    ] = None,
+    auto_fetch_tasks: Annotated[
+        bool | None,
+        typer.Option(
+            "--auto-fetch-tasks/--no-auto-fetch-tasks",
+            help="Fall back to task queue when command queue is empty",
+        ),
+    ] = None,
+    api_key: Annotated[
+        str | None,
+        typer.Option(
+            "--key",
+            "-k",
+            help="API key for steerdev.com (overrides STEERDEV_API_KEY env var)",
+            envvar="STEERDEV_API_KEY",
+        ),
+    ] = None,
+) -> None:
+    """Run the agent in persistent daemon mode.
+
+    The daemon runs indefinitely, polling for commands from the dashboard/API.
+    When the command queue is empty and --auto-fetch-tasks is enabled (default),
+    it falls back to fetching the next task from the task queue.
+
+    Each command/task execution creates a session with full event streaming.
+    Send a 'shutdown' control command or press Ctrl+C to stop.
+
+    Example:
+        steerdev daemon --project-id abc123 --agent-name my-agent
+        steerdev daemon --project-id abc123 --agent-name my-agent --no-auto-fetch-tasks
+        steerdev daemon --project-id abc123 --agent-name my-agent --poll-interval 10
+    """
+    from steerdev_agent.daemon import run_daemon
+
+    # Get config from context (loaded in app callback)
+    config: SteerDevConfig = ctx.obj or SteerDevConfig()
+
+    # Resolve project_id: CLI > env (handled by typer) > config env var
+    resolved_project_id = project_id
+    if not resolved_project_id:
+        resolved_project_id = os.environ.get(config.api.project_id_env)
+    if not resolved_project_id:
+        console.print("[red]Error: --project-id required (or set via env/config)[/red]")
+        raise typer.Exit(1)
+
+    # Agent name is required for daemon mode
+    if not agent_name:
+        console.print(
+            "[red]Error: --agent-name required (or set STEERDEV_AGENT_NAME env var)[/red]"
+        )
+        raise typer.Exit(1)
+
+    # Resolve options: CLI > config > default
+    resolved_model = model if model is not None else config.agent.model
+    resolved_max_turns = max_turns if max_turns is not None else config.agent.max_turns
+
+    # API key: CLI > env (via envvar) > config env var
+    resolved_api_key = api_key
+    if not resolved_api_key:
+        resolved_api_key = os.environ.get(config.api.api_key_env)
+
+    # Build daemon config with CLI overrides
+    daemon_config = config.daemon.model_copy()
+    if poll_interval is not None:
+        daemon_config.poll_interval_seconds = poll_interval
+    if auto_fetch_tasks is not None:
+        daemon_config.auto_fetch_tasks = auto_fetch_tasks
+
+    try:
+        asyncio.run(
+            run_daemon(
+                project_id=resolved_project_id,
+                agent_name=agent_name,
+                working_directory=str(working_dir) if working_dir else None,
+                api_key=resolved_api_key,
+                model=resolved_model,
+                max_turns=resolved_max_turns,
+                daemon_config=daemon_config,
+                executor_config=config.executor,
+            )
+        )
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Daemon stopped[/yellow]")
+        raise typer.Exit(0) from None
+    except Exception as e:
+        console.print(f"\n[red]Daemon error: {e}[/red]")
+        raise typer.Exit(1) from e
+
+
+@app.command()
+def resume(
+    ctx: typer.Context,
+    session_id: Annotated[
+        str,
+        typer.Option(
+            "--session-id",
+            "-s",
+            help="Session ID to resume (required)",
+        ),
+    ],
+    message: Annotated[
+        str,
+        typer.Option(
+            "--message",
+            "-m",
+            help="Message to continue the conversation (required)",
+        ),
+    ],
+    api_key: Annotated[
+        str | None,
+        typer.Option(
+            "--key",
+            "-k",
+            help="API key for steerdev.com",
+            envvar="STEERDEV_API_KEY",
+        ),
+    ] = None,
+    dry_run: Annotated[
+        bool,
+        typer.Option(
+            "--dry",
+            help="Print the command that would be run without executing it",
+        ),
+    ] = False,
+) -> None:
+    """Resume an existing session with a new message.
+
+    Example:
+        steerdev resume --session-id abc123 --message "Continue working..."
+    """
+    from steerdev_agent.runner import resume_session
+
+    # Get config from context (loaded in app callback)
+    config: SteerDevConfig = ctx.obj or SteerDevConfig()
+
+    # Resolve API key: CLI > env (via envvar) > config env var
+    resolved_api_key = api_key
+    if not resolved_api_key:
+        resolved_api_key = os.environ.get(config.api.api_key_env)
+
+    dry_run_status = "enabled" if dry_run else "disabled"
+
+    console.print(
+        Panel(
+            f"[bold blue]Resuming Session[/bold blue]\n"
+            f"Session ID: {session_id}\n"
+            f"Message: {message[:100]}{'...' if len(message) > 100 else ''}\n"
+            f"Dry Run: {dry_run_status}",
+            title="Resume",
+        )
+    )
+
+    try:
+        result = asyncio.run(
+            resume_session(
+                session_id=session_id,
+                message=message,
+                api_key=resolved_api_key,
+                dry_run=dry_run,
+            )
+        )
+
+        if result.get("success"):
+            console.print(
+                Panel(
+                    f"[bold green]Session resumed successfully[/bold green]\n"
+                    f"Events Sent: {result.get('events_sent', 0)}",
+                    title="Complete",
+                )
+            )
+        else:
+            console.print(f"[red]Resume failed: {result.get('error', 'Unknown')}[/red]")
+            raise typer.Exit(1)
+
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Interrupted by user[/yellow]")
+        raise typer.Exit(130) from None
+    except Exception as e:
+        console.print(f"\n[red]Error: {e}[/red]")
+        raise typer.Exit(1) from e
+
+
+def _prompt_install_target() -> str:
+    """Prompt the user to choose where to install Claude configs."""
+    choices = {
+        "1": ("project", ".claude/ in the project directory (project-specific)"),
+        "2": ("user", "~/.claude/ in your home directory (shared across projects)"),
+    }
+
+    console.print("\n[bold]Where should steerdev agent configs be installed?[/bold]\n")
+    for key, (_, description) in choices.items():
+        console.print(f"  [cyan]{key}[/cyan]) {description}")
+    console.print()
+
+    while True:
+        choice = typer.prompt("Select install target", default="1")
+        if choice in choices:
+            selected = choices[choice][0]
+            console.print(f"\n[dim]Selected: {selected}[/dim]\n")
+            return selected
+        console.print(f"[red]Invalid choice '{choice}'. Enter 1 or 2.[/red]")
+
+
+@app.command()
+def setup(
+    project_dir: Annotated[
+        Path | None,
+        typer.Option(
+            "--dir",
+            "-d",
+            help="Target project directory (defaults to current directory)",
+            exists=True,
+            file_okay=False,
+            dir_okay=True,
+        ),
+    ] = None,
+    project_id: Annotated[
+        str | None,
+        typer.Option(
+            "--project-id",
+            "-p",
+            help="SteerDev project ID to configure",
+        ),
+    ] = None,
+    api_key: Annotated[
+        str | None,
+        typer.Option(
+            "--api-key",
+            "-k",
+            help="SteerDev API key to configure",
+        ),
+    ] = None,
+    agent_name: Annotated[
+        str | None,
+        typer.Option(
+            "--agent-name",
+            "-n",
+            help="Agent name for session tracking (generates a random name if not provided)",
+        ),
+    ] = None,
+    install_target: Annotated[
+        str | None,
+        typer.Option(
+            "--install-target",
+            "-i",
+            help="Where to install configs: 'project' (.claude/) or 'user' (~/.claude/)",
+        ),
+    ] = None,
+    force: Annotated[
+        bool,
+        typer.Option(
+            "--force",
+            "-f",
+            help="Overwrite existing files",
+        ),
+    ] = False,
+    skip_claude_md: Annotated[
+        bool,
+        typer.Option(
+            "--skip-claude-md",
+            help="Skip updating CLAUDE.md",
+        ),
+    ] = False,
+) -> None:
+    """Set up Claude Code integration for steerdev.com task management.
+
+    This command configures a project with:
+    - .claude/settings.json with permissions for CLI commands and hooks
+    - .claude/skills/task-management/ skill for autonomous task management
+    - .env file with steerdev configuration variables (including agent name)
+    - CLAUDE.md section with task management instructions
+
+    Use --install-target to choose where configs are installed:
+    - project: .claude/ in the project directory (default for team/project-specific configs)
+    - user: ~/.claude/ in your home directory (shared across all projects)
+    """
+    from steerdev_agent.setup import ClaudeSetup
+
+    target_dir = project_dir or Path.cwd()
+
+    # Prompt for install target if not provided
+    if install_target is None:
+        install_target = _prompt_install_target()
+
+    # Validate install target
+    if install_target not in ("project", "user"):
+        console.print(
+            f"[red]Error: Invalid install target '{install_target}'. "
+            f"Must be 'project' or 'user'.[/red]"
+        )
+        raise typer.Exit(1)
+
+    setup_instance = ClaudeSetup(target_dir, install_target=install_target)
+
+    claude_dir_display = "~/.claude/" if install_target == "user" else f"{target_dir}/.claude/"
+
+    console.print(
+        Panel(
+            f"[bold blue]Setting up Claude Code integration[/bold blue]\n"
+            f"Target directory: {target_dir}\n"
+            f"Install target: {install_target} ({claude_dir_display})",
+            title="SteerDev Setup",
+        )
+    )
+
+    def _display_path(p: Path) -> str:
+        """Display a path relative to project dir, or using ~ for home."""
+        try:
+            return str(p.relative_to(target_dir))
+        except ValueError:
+            # Path is outside project dir (e.g., ~/.claude/)
+            home = Path.home()
+            try:
+                return "~/" + str(p.relative_to(home))
+            except ValueError:
+                return str(p)
+
+    try:
+        # Setup settings (with hooks config)
+        settings_path = setup_instance.setup_settings(force=force, include_hooks=True)
+        console.print(f"[green]✓[/green] Settings: {_display_path(settings_path)}")
+
+        # Setup skills
+        skills_path = setup_instance.setup_skills(force=force)
+        console.print(f"[green]✓[/green] Skills: {_display_path(skills_path)}")
+
+        # Setup .env file (generates agent name if not provided)
+        env_path, env_updated = setup_instance.setup_env(
+            project_id=project_id,
+            api_key=api_key,
+            agent_name=agent_name,
+        )
+        if env_updated:
+            console.print(f"[green]✓[/green] .env: {_display_path(env_path)}")
+        else:
+            console.print(f"[dim]○[/dim] .env already configured: {_display_path(env_path)}")
+
+        # Setup CLAUDE.md
+        if not skip_claude_md:
+            updated = setup_instance.update_claude_md(force=force)
+            if updated:
+                console.print("[green]✓[/green] CLAUDE.md updated with task management section")
+            else:
+                console.print("[dim]○[/dim] CLAUDE.md already has task management section")
+        else:
+            console.print("[dim]○[/dim] Skipped CLAUDE.md update")
+
+        # Add steerdev.yaml config
+        config_path, config_created = setup_instance.setup_steerdev_config(force=force)
+        if config_created:
+            console.print(f"[green]✓[/green] Config: {_display_path(config_path)}")
+        else:
+            console.print(f"[dim]○[/dim] Config already exists: {_display_path(config_path)}")
+
+        # Sync shared agent settings if credentials are available
+        if project_id and api_key:
+            try:
+                console.print("\n[blue]Syncing shared agent settings...[/blue]")
+                platform_config = asyncio.run(_sync_configs(project_id))
+                if platform_config is None:
+                    raise RuntimeError("Failed to fetch platform configs")
+                counts = setup_instance.apply_platform_configs(platform_config)
+                _save_synced_at(target_dir, platform_config.synced_at)
+                total = sum(counts.values())
+                if total > 0:
+                    console.print(f"[green]✓[/green] Synced {total} shared setting(s)")
+                else:
+                    console.print("[dim]○[/dim] No shared settings configured")
+            except Exception as e:
+                console.print(f"[yellow]⚠[/yellow] Could not sync settings: {e}")
+
+        # Show different messages based on whether credentials were provided
+        if project_id and api_key:
+            next_steps = (
+                "[bold green]Setup complete![/bold green]\n\n"
+                "Your project is configured and ready to use.\n\n"
+                "Run the agent:\n"
+                "  steerdev run\n\n"
+                "Commands available:\n"
+                "  steerdev run --help\n"
+                "  steerdev resume --help\n"
+                "  steerdev tasks --help\n"
+                "  steerdev sessions --help"
+            )
+        else:
+            next_steps = (
+                "[bold green]Setup complete![/bold green]\n\n"
+                "Next steps:\n"
+                "1. Edit .env and set your STEERDEV_API_KEY and STEERDEV_PROJECT_ID\n"
+                "2. Run: steerdev run\n\n"
+                "Commands available:\n"
+                "  steerdev run --help\n"
+                "  steerdev resume --help\n"
+                "  steerdev tasks --help\n"
+                "  steerdev sessions --help"
+            )
+
+        console.print(
+            Panel(
+                next_steps,
+                title="Done",
+                border_style="green",
+            )
+        )
+
+    except Exception as e:
+        console.print(f"[red]Error during setup: {e}[/red]")
+        raise typer.Exit(1) from e
+
+
+@app.command()
+def sync(
+    project_dir: Annotated[
+        Path | None,
+        typer.Option(
+            "--dir",
+            "-d",
+            help="Target project directory (defaults to current directory)",
+            exists=True,
+            file_okay=False,
+            dir_okay=True,
+        ),
+    ] = None,
+    project_id: Annotated[
+        str | None,
+        typer.Option(
+            "--project-id",
+            "-p",
+            help="SteerDev project ID",
+            envvar="STEERDEV_PROJECT_ID",
+        ),
+    ] = None,
+    install_target: Annotated[
+        str,
+        typer.Option(
+            "--install-target",
+            "-i",
+            help="Where configs are installed: 'project' (.claude/) or 'user' (~/.claude/)",
+        ),
+    ] = "project",
+) -> None:
+    """Sync shared agent settings from steerdev.com.
+
+    Pulls the latest shared configurations (system prompts, skills, MCP servers,
+    env variables) from the platform and applies them to the local project.
+
+    This updates:
+    - CLAUDE.md with shared system prompts
+    - .claude/skills/ with synced skills
+    - .claude/settings.json with MCP server configurations
+    - .env with shared environment variables
+    """
+    import yaml
+
+    target_dir = project_dir or Path.cwd()
+
+    # Resolve project_id from env/config if not provided
+    resolved_project_id = project_id
+    if not resolved_project_id:
+        resolved_project_id = os.environ.get("STEERDEV_PROJECT_ID")
+    if not resolved_project_id:
+        # Try from steerdev.yaml
+        config_path = target_dir / "steerdev.yaml"
+        if config_path.exists():
+            config_data = yaml.safe_load(config_path.read_text())
+            env_name = config_data.get("api", {}).get("project_id_env", "STEERDEV_PROJECT_ID")
+            resolved_project_id = os.environ.get(env_name)
+
+    if not resolved_project_id:
+        console.print("[red]Error: --project-id required (or set STEERDEV_PROJECT_ID)[/red]")
+        raise typer.Exit(1)
+
+    console.print(
+        Panel(
+            f"[bold blue]Syncing shared agent settings[/bold blue]\n"
+            f"Project: {resolved_project_id}\n"
+            f"Directory: {target_dir}",
+            title="SteerDev Sync",
+        )
+    )
+
+    try:
+        from steerdev_agent.setup import ClaudeSetup
+
+        # Fetch configs from API
+        platform_config = asyncio.run(_sync_configs(resolved_project_id))
+        if platform_config is None:
+            console.print("[yellow]⚠[/yellow] No configs returned from API")
+            raise typer.Exit(1)
+
+        # Apply to local project
+        setup_instance = ClaudeSetup(target_dir, install_target=install_target)
+        counts = setup_instance.apply_platform_configs(platform_config)
+
+        # Save synced_at timestamp to steerdev.yaml
+        _save_synced_at(target_dir, platform_config.synced_at)
+
+        # Display results
+        total = sum(counts.values())
+        if total > 0:
+            details = []
+            if counts["system_prompts"]:
+                details.append(f"System prompts: {counts['system_prompts']}")
+            if counts["skills"]:
+                details.append(f"Skills: {counts['skills']}")
+            if counts["mcps"]:
+                details.append(f"MCP servers: {counts['mcps']}")
+            if counts["env_vars"]:
+                details.append(f"Env variables: {counts['env_vars']}")
+            console.print(
+                Panel(
+                    "[bold green]Sync complete[/bold green]\n" + "\n".join(details),
+                    title="Done",
+                    border_style="green",
+                )
+            )
+        else:
+            console.print("[yellow]No shared settings configured for this project.[/yellow]")
+
+    except Exception as e:
+        console.print(f"[red]Error during sync: {e}[/red]")
+        raise typer.Exit(1) from e
+
+
+async def _sync_configs(project_id: str):
+    """Fetch platform configs via async API client."""
+    from steerdev_agent.api.configs import ConfigsClient
+
+    async with ConfigsClient() as client:
+        return await client.sync_configs(project_id)
+
+
+def _save_synced_at(target_dir: Path, synced_at: str) -> None:
+    """Save the synced_at timestamp to steerdev.yaml."""
+    import yaml
+
+    config_path = target_dir / "steerdev.yaml"
+    config_data = yaml.safe_load(config_path.read_text()) or {} if config_path.exists() else {}
+    config_data["synced_at"] = synced_at
+    config_path.write_text(yaml.dump(config_data, default_flow_style=False))
+
+
+def _check_sync_staleness(target_dir: Path) -> None:
+    """Check if synced configs are stale and print a warning."""
+    from datetime import UTC, datetime, timedelta
+
+    import yaml
+
+    config_path = target_dir / "steerdev.yaml"
+    if not config_path.exists():
+        return
+
+    try:
+        config_data = yaml.safe_load(config_path.read_text()) or {}
+        synced_at_str = config_data.get("synced_at")
+        if not synced_at_str:
+            return
+
+        synced_at = datetime.fromisoformat(synced_at_str.replace("Z", "+00:00"))
+        now = datetime.now(UTC)
+        if now - synced_at > timedelta(hours=1):
+            age_hours = (now - synced_at).total_seconds() / 3600
+            console.print(
+                f"[yellow]Warning: Shared agent settings may be out of date "
+                f"(last synced {age_hours:.0f}h ago). "
+                f"Run `steerdev sync` to update.[/yellow]"
+            )
+    except Exception:
+        pass  # Don't block execution on staleness check errors
+
+
+@app.command("test")
+def integration_test(
+    project_id: Annotated[
+        str,
+        typer.Option(
+            "--project-id",
+            "-p",
+            help="SteerDev project ID to add tasks to",
+        ),
+    ],
+    project_dir: Annotated[
+        Path,
+        typer.Option(
+            "--dir",
+            "-d",
+            help="Directory to create the test project in",
+        ),
+    ],
+    tasks_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--tasks-file",
+            "-t",
+            help="JSON file with custom tasks (uses default todo-api tasks if not provided)",
+        ),
+    ] = None,
+    skip_tasks: Annotated[
+        bool,
+        typer.Option(
+            "--skip-tasks",
+            help="Skip adding tasks to the project",
+        ),
+    ] = False,
+    auto_start: Annotated[
+        bool,
+        typer.Option(
+            "--auto-start",
+            "-y",
+            help="Start the agent without confirmation",
+        ),
+    ] = False,
+) -> None:
+    """Run an integration test with a fresh todo-list API project.
+
+    Creates a new Python project using `uv init` and adds tasks for building
+    a todo-list API with FastAPI and SQLite. Useful for testing the agent
+    end-to-end in a controlled environment.
+
+    Example:
+        steerdev integration-test -p YOUR_PROJECT_UUID
+        steerdev integration-test -p YOUR_PROJECT_UUID -y  # auto-start
+    """
+    from steerdev_agent.integration import run_integration_test
+
+    run_integration_test(
+        project_id=project_id,
+        project_dir=project_dir,
+        tasks_file=tasks_file,
+        skip_tasks=skip_tasks,
+        auto_start=auto_start,
+    )
+
+
+if __name__ == "__main__":
+    app()