forgex-cli 0.1.0__py3-none-any.whl

forgex/cli/app.py

@@ -0,0 +1,232 @@
+"""Typer application assembly and the controlled-error entry point."""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Annotated
+
+from typer._click import Command, Context
+import typer
+from rich.console import Console
+
+from forgex import __version__
+from forgex.cli.commands import (
+    build as build_cmd,
+)
+from forgex.cli.commands import (
+    checkpoint as checkpoint_cmd,
+)
+from forgex.cli.commands import (
+    config as config_cmd,
+)
+from forgex.cli.commands import (
+    context as context_cmd,
+)
+from forgex.cli.commands import (
+    diff as diff_cmd,
+)
+from forgex.cli.commands import (
+    do_cmd,
+)
+from forgex.cli.commands import (
+    doctor as doctor_cmd,
+)
+from forgex.cli.commands import (
+    fix as fix_cmd,
+)
+from forgex.cli.commands import (
+    init as init_cmd,
+)
+from forgex.cli.commands import (
+    logs as logs_cmd,
+)
+from forgex.cli.commands import (
+    models as models_cmd,
+)
+from forgex.cli.commands import (
+    plan as plan_cmd,
+)
+from forgex.cli.commands import (
+    review as review_cmd,
+)
+from forgex.cli.commands import (
+    rollback as rollback_cmd,
+)
+from forgex.cli.commands import (
+    run as run_cmd,
+)
+from forgex.cli.commands import (
+    status as status_cmd,
+)
+from forgex.cli.commands import (
+    supervise as supervise_cmd,
+)
+from forgex.cli.commands import (
+    task as task_cmd,
+)
+from forgex.cli.commands import (
+    tools as tools_cmd,
+)
+from forgex.cli.commands import (
+    verify as verify_cmd,
+)
+from forgex.cli.repl import start_repl
+from forgex.config.loader import load_env_files
+from forgex.schemas.error import ForgexError
+from forgex.utils.logging import configure_logging
+from forgex.utils.paths import find_project_root
+
+
+class ForgexTyperGroup(typer.core.TyperGroup):
+    """Custom TyperGroup that routes unrecognized command inputs to autonomous execution."""
+
+    def resolve_command(
+        self, ctx: Context, args: list[str]
+    ) -> tuple[str | None, Command | None, list[str]]:
+        if not args:
+            return super().resolve_command(ctx, args)
+        cmd_name = args[0]
+        # Registered commands or options start with '-'
+        if cmd_name in self.commands or cmd_name.startswith("-"):
+            return super().resolve_command(ctx, args)
+        # Unrecognized command / natural language prose -> route to 'do' with full args
+        cmd = self.get_command(ctx, "do")
+        return "do", cmd, args
+
+    def get_command(self, ctx: Context, cmd_name: str) -> Command | None:
+        cmd = super().get_command(ctx, cmd_name)
+        if cmd is not None:
+            return cmd
+        if not cmd_name.startswith("-") and "do" in self.commands:
+            return self.commands["do"]
+        return None
+
+
+app = typer.Typer(
+    cls=ForgexTyperGroup,
+    name="forgex",
+    help="FORGEX — autonomous multi-agent AI software engineering. Plan. Build. Refine. Verify.",
+    no_args_is_help=False,
+    add_completion=True,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"forgex {__version__}")
+        raise typer.Exit
+
+
+@app.callback(invoke_without_command=True)
+def root(
+    ctx: typer.Context,
+    version: Annotated[bool | None, typer.Option("--version", callback=_version_callback, is_eager=True, help="Show version and exit.")] = None,
+    no_repl: Annotated[bool, typer.Option("--no-repl", help="Do not start interactive REPL when no command given.")] = False,
+    verbose: Annotated[bool, typer.Option("--verbose", "-v", help="Verbose logging.")] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", help="Suppress non-essential output.")] = False,
+    json_out: Annotated[bool, typer.Option("--json", help="Machine-readable JSON output.")] = False,
+    plain: Annotated[bool, typer.Option("--plain", help="Plain output (CI/SSH safe).")] = False,
+    debug: Annotated[bool, typer.Option("--debug", help="Show full tracebacks on errors.")] = False,
+    offline: Annotated[bool, typer.Option("--offline", help="Offline mode: no web research, no remote providers.")] = False,
+) -> None:
+    """FORGEX — an AI software engineering team for your terminal."""
+    if offline:
+        os.environ["FORGEX_OFFLINE"] = "1"
+    if debug:
+        os.environ["FORGEX_DEBUG"] = "1"
+
+    load_env_files(find_project_root())
+    configure_logging(level="debug" if verbose else "warning")
+    ctx.obj = {"verbose": verbose, "quiet": quiet, "json": json_out, "plain": plain}
+
+    if ctx.invoked_subcommand is None:
+        import sys
+
+        if no_repl or not sys.stdin.isatty():
+            typer.echo(ctx.get_help())
+            raise typer.Exit()
+        start_repl()
+        raise typer.Exit()
+
+
+def repl_command() -> None:
+    """Start interactive persistent REPL session."""
+    start_repl()
+
+
+# Register all commands
+app.command(name="repl", help="Start interactive persistent REPL session.")(repl_command)
+app.command(name="init", help="Initialize FORGEX in a project directory.")(init_cmd.init_command)
+app.command(name="doctor", help="Check environment, tools and configuration.")(doctor_cmd.doctor_command)
+app.command(name="status", help="Show project status.")(status_cmd.status_command)
+app.add_typer(config_cmd.app, name="config", help="View and modify configuration.")
+app.command(name="logs", help="Show recorded FORGEX events.")(logs_cmd.logs_command)
+app.add_typer(models_cmd.app, name="models", help="Inspect model bindings, catalog, and provider health.")
+app.add_typer(tools_cmd.app, name="tools", help="Inspect and manually run FORGEX tools.")
+app.command(name="plan", help="Run the Architect: analysis, research, implementation plan.")(plan_cmd.plan_command)
+app.add_typer(task_cmd.app, name="task", help="Inspect and execute plan tasks.")
+app.command(name="checkpoint", help="Create a Git checkpoint of the current state.")(checkpoint_cmd.checkpoint_command)
+app.command(name="rollback", help="Roll back to a checkpoint (reversible).")(rollback_cmd.rollback_command)
+app.command(name="diff", help="Show the current Git diff.")(diff_cmd.diff_command)
+app.command(name="review", help="Expert review of recent changes.")(review_cmd.review_command)
+app.command(name="verify", help="Run tests/build/lint — deterministic, no LLM.")(verify_cmd.verify_command)
+app.command(name="supervise", help="Full supervision: verification + audit + verdict.")(supervise_cmd.supervise_command)
+app.command(name="build", help="Full build: plan → build → review → verify → supervise → repair loop.")(build_cmd.build_command)
+app.command(name="fix", help="Verify, supervise, and repair until green — no rebuild.")(fix_cmd.fix_command)
+app.command(name="do", help="Autonomous execution: auto-init → plan → build → verify → repair → checkpoint.")(do_cmd.do_command)
+app.command(name="run", help="Run the project's start command.")(run_cmd.run_command)
+app.add_typer(context_cmd.app, name="context", help="Inspect the context index and retrieval.")
+
+REGISTERED_COMMANDS = {
+    "repl",
+    "init",
+    "doctor",
+    "status",
+    "config",
+    "logs",
+    "models",
+    "tools",
+    "plan",
+    "task",
+    "checkpoint",
+    "rollback",
+    "diff",
+    "review",
+    "verify",
+    "supervise",
+    "build",
+    "fix",
+    "run",
+    "context",
+    "do",
+}
+
+
+def main() -> None:
+    """Console-script entry point with controlled error handling."""
+    # Natural language command line routing:
+    # If user invokes `forgex "add auth"` or `forgex build me a bot`, route to `do` command.
+    if len(sys.argv) > 1:
+        first = sys.argv[1].lower()
+        if not first.startswith("-") and first not in REGISTERED_COMMANDS or first == "build" and len(sys.argv) > 2 and not any(a.startswith("-") for a in sys.argv[2:]):
+            sys.argv = [sys.argv[0], "do", *sys.argv[1:]]
+
+    try:
+        app()
+    except ForgexError as exc:
+        if os.environ.get("FORGEX_DEBUG"):
+            raise
+        Console(stderr=True).print(f"[red]✗[/red] {exc}")
+        raise SystemExit(exc.exit_code) from None
+    except KeyboardInterrupt:
+        Console(stderr=True).print("[yellow]Interrupted — on-disk state is preserved.[/yellow]")
+        raise SystemExit(130) from None
+    except Exception as exc:
+        if os.environ.get("FORGEX_DEBUG"):
+            raise
+        err = Console(stderr=True)
+        err.print(f"[red]✗[/red] internal error: {type(exc).__name__}: {exc}")
+        err.print("[dim]re-run with --debug for the full traceback[/dim]")
+        raise SystemExit(70) from None

forgex/cli/build_views.py

@@ -0,0 +1,94 @@
+"""Shared output formatters for build and fix commands."""
+
+from __future__ import annotations
+
+from rich.markup import escape
+from rich.panel import Panel
+
+from forgex.cli.ui import UI, Output
+from forgex.orchestration.engine import BuildRunResult
+
+
+def _tests_line(result: BuildRunResult) -> str:
+    tests = result.tests
+    if tests is None:
+        return "not run"
+    if tests.passed is None:
+        return f"exit {tests.exit_code}"
+    return f"{tests.passed} passed, {tests.failed or 0} failed"
+
+
+def format_progress(line: str, *, rich_mode: bool) -> str:
+    """Format an agent progress message with modern terminal styling."""
+    if not rich_mode:
+        return line
+    styled = line
+    if "Architect:" in line:
+        styled = line.replace("Architect:", "[bold cyan]● [Architect][/bold cyan]")
+    elif "Plan created:" in line:
+        styled = f"[green]✓[/green] [bold]{line}[/bold]"
+    elif "Builder:" in line or "Task " in line:
+        styled = line.replace("Builder:", "[bold blue]● [Builder][/bold blue]")
+    elif "FAILED" in line:
+        styled = f"[red]✗[/red] {line}"
+    elif "Supervisor:" in line:
+        styled = line.replace("Supervisor:", "[bold magenta]● [Supervisor][/bold magenta]")
+    elif "Self-healing" in line:
+        styled = f"[bold yellow]⟳ {line}[/bold yellow]"
+    elif "Testing" in line or "quality verification" in line:
+        styled = f"[bold yellow]● [Verification][/bold yellow] {line}"
+    return styled
+
+
+def _render_success(ui: UI, result: BuildRunResult) -> None:
+    if ui.mode is Output.RICH:
+        ui.console.print(Panel("[bold green]FORGEX BUILD COMPLETE[/bold green]", expand=False))
+    lines = [
+        f"Tasks       {result.tasks_completed}/{result.tasks_total}",
+        f"Files       {len(result.changed_files)} changed",
+        f"Tests       {_tests_line(result)}",
+        f"Build       {'passed' if result.build_ok else 'failed' if result.build_ok is False else '—'}",
+        f"Supervisor  {result.verdict}",
+        f"Iterations  {result.iterations}",
+        f"Checkpoint  {result.checkpoint[:8] if result.checkpoint else '—'}",
+    ]
+    if result.usage:
+        prompt_tok = result.usage.get("prompt_tokens") or 0
+        comp_tok = result.usage.get("completion_tokens") or 0
+        cost = result.usage.get("estimated_cost_usd")
+        if prompt_tok > 0 or comp_tok > 0:
+            cost_str = f" (${cost:.4f})" if cost is not None else ""
+            lines.append(f"Tokens      {prompt_tok:,} in / {comp_tok:,} out{cost_str}")
+    for line in lines:
+        ui.text(line)
+    if result.changed_files and ui.mode in (Output.RICH, Output.PLAIN):
+        ui.text("")
+        ui.text("Changed files:")
+        for path in result.changed_files[:30]:
+            ui.text(f"  {escape(path)}")
+    for warning in result.warnings:
+        ui.warn(warning)
+
+
+def _render_failure(ui: UI, result: BuildRunResult) -> None:
+    if ui.mode is Output.RICH:
+        ui.console.print(Panel(f"[bold red]FORGEX BUILD FAILED[/bold red]\n{result.reason}", expand=False))
+    else:
+        ui.error(f"FORGEX BUILD FAILED: {result.reason}")
+
+    lines = [
+        f"Tasks       {result.tasks_completed}/{result.tasks_total}",
+        f"Remaining   {', '.join(result.remaining_tasks) or 'none'}",
+        f"Tests       {_tests_line(result)}",
+        f"Supervisor  {result.verdict}",
+        f"Iterations  {result.iterations}",
+    ]
+    if result.usage:
+        prompt_tok = result.usage.get("prompt_tokens") or 0
+        comp_tok = result.usage.get("completion_tokens") or 0
+        cost = result.usage.get("estimated_cost_usd")
+        if prompt_tok > 0 or comp_tok > 0:
+            cost_str = f" (${cost:.4f})" if cost is not None else ""
+            lines.append(f"Tokens      {prompt_tok:,} in / {comp_tok:,} out{cost_str}")
+    for line in lines:
+        ui.text(line)

forgex/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command modules."""

forgex/cli/commands/build.py

@@ -0,0 +1,63 @@
+"""`forgex build` — full multi-agent build pipeline with repair loop (spec sections 12, 22, 57, 58)."""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from forgex.cli.build_views import _render_failure, _render_success, format_progress
+from forgex.cli.ui import JsonFlag, Output, PlainFlag, make_approval, ui_from
+from forgex.config import load_config
+from forgex.orchestration.engine import BuildEngine, DryRunReport
+from forgex.orchestration.stores import open_stores
+from forgex.schemas.error import ProjectError
+from forgex.utils.paths import find_project_root
+
+
+def build_command(
+    ctx: typer.Context,
+    request: Annotated[str | None, typer.Argument(help="What should be built?")] = None,
+    file: Annotated[Path | None, typer.Option("--file", "-f", help="Read user request from file.")] = None,
+    resume: Annotated[bool, typer.Option("--resume", "-r", help="Resume interrupted build.")] = False,
+    dry_run: Annotated[bool, typer.Option("--dry-run", help="Show execution preview without making changes.")] = False,
+    json_out: JsonFlag = False,
+    plain: PlainFlag = False,
+) -> None:
+    """Full build: plan → build → review → verify → supervise → repair loop."""
+    ui = ui_from(ctx, json_out=json_out, plain=plain)
+    root = find_project_root()
+    if root is None:
+        raise ProjectError("Not inside a FORGEX project — run `forgex init` first.")
+
+    user_req = request
+    if file and file.is_file():
+        user_req = file.read_text(encoding="utf-8")
+
+    config = load_config(root)
+    with open_stores(root) as stores:
+        engine = BuildEngine(
+            stores=stores,
+            config=config,
+            approval=make_approval(ui),
+            progress=lambda line: ui.text(format_progress(line, rich_mode=(ui.mode is Output.RICH))),
+        )
+        result = asyncio.run(engine.run(user_req, dry_run=dry_run, resume=resume))
+
+    if isinstance(result, DryRunReport):
+        ui.data(result.model_dump(mode="json"))
+        ui.ok(f"Dry run preview: {len(result.planned_tasks)} planned tasks, {len(result.planned_files)} files.")
+        for t in result.planned_tasks:
+            ui.text(f"  - [{t.get('priority')}] {t.get('id')}: {t.get('description')}")
+        return
+
+    ui.data(result.model_dump(mode="json"))
+    if ui.mode in (Output.RICH, Output.PLAIN):
+        if result.status == "completed":
+            _render_success(ui, result)
+        else:
+            _render_failure(ui, result)
+
+    raise typer.Exit(code=0 if result.status == "completed" else 1)

forgex/cli/commands/checkpoint.py

@@ -0,0 +1,41 @@
+"""`forgex checkpoint` — create a Git checkpoint of current state (spec section 21)."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from forgex.cli.ui import JsonFlag, PlainFlag, ui_from
+from forgex.orchestration.checkpoints import create_checkpoint
+from forgex.orchestration.stores import open_stores
+from forgex.schemas.error import ProjectError
+from forgex.tools.git import has_git_repo
+from forgex.utils.paths import find_project_root
+
+
+def checkpoint_command(
+    ctx: typer.Context,
+    label: Annotated[str | None, typer.Argument(help="Checkpoint label")] = None,
+    json_out: JsonFlag = False,
+    plain: PlainFlag = False,
+) -> None:
+    """Commit all current work as a FORGEX checkpoint."""
+    ui = ui_from(ctx, json_out=json_out, plain=plain)
+    root = find_project_root()
+    if root is None:
+        raise ProjectError("Not inside a FORGEX project — run `forgex init` first.")
+
+    if not has_git_repo(root):
+        ui.warn("No git repository detected — checkpointing requires git. Run 'git init'.")
+        raise typer.Exit(code=0)
+
+    with open_stores(root) as stores:
+        record = create_checkpoint(label or "manual", stores=stores)
+
+    if record is None:
+        ui.error("Checkpoint failed (git error — see git status).")
+        raise typer.Exit(code=1)
+
+    ui.data({"id": record.id, "label": record.label, "git_commit": record.git_commit})
+    ui.ok(f"Checkpoint {record.id} — {record.git_commit[:8] if record.git_commit else '?'} ({record.label})")

forgex/cli/commands/config.py

@@ -0,0 +1,225 @@
+"""`forgex config` — view and modify layered configuration."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from rich.prompt import Confirm, Prompt
+
+from forgex.cli.ui import JsonFlag, PlainFlag, ui_from
+from forgex.config import (
+    CONFIG_FILE_NAME,
+    global_config_path,
+    load_config,
+    project_config_path,
+    set_config_value,
+    store_secret,
+)
+from forgex.schemas.error import ConfigError
+from forgex.utils.paths import find_project_root
+
+app = typer.Typer(no_args_is_help=True, help="View and modify FORGEX configuration.")
+
+GlobalFlag = Annotated[
+    bool,
+    typer.Option("--global", "-g", help="Operate on ~/.forgex/config.toml instead of project config."),
+]
+
+
+def _target_path(global_: bool) -> Path:
+    if global_:
+        return global_config_path()
+    root = find_project_root()
+    if root is None:
+        raise ConfigError("Not inside a FORGEX project. Use --global to edit global configuration.")
+    return project_config_path(root)
+
+
+def _get_dotted(data: dict[str, Any], dotted: str) -> Any:
+    node: Any = data
+    for part in dotted.split("."):
+        if not isinstance(node, dict) or part not in node:
+            raise ConfigError(f"Configuration key '{dotted}' not found")
+        node = node[part]
+    return node
+
+
+@app.command("show")
+def show_command(
+    ctx: typer.Context,
+    json_out: JsonFlag = False,
+    plain: PlainFlag = False,
+) -> None:
+    """Show the currently active merged configuration."""
+    ui = ui_from(ctx, json_out=json_out, plain=plain)
+    root = find_project_root()
+    config = load_config(root)
+    payload = config.model_dump(mode="json", exclude_none=True)
+    ui.data(payload)
+    if not json_out and not ctx.obj.get("json"):
+        ui.text(json.dumps(payload, indent=2))
+
+
+@app.command("get")
+def get_command(
+    ctx: typer.Context,
+    key: Annotated[str, typer.Argument(help="Dotted configuration key, e.g. workflow.max_iterations")],
+    json_out: JsonFlag = False,
+    plain: PlainFlag = False,
+) -> None:
+    """Get a configuration value by dotted key."""
+    ui = ui_from(ctx, json_out=json_out, plain=plain)
+    root = find_project_root()
+    config = load_config(root)
+    val = _get_dotted(config.model_dump(mode="json"), key)
+    ui.data({"key": key, "value": val})
+    if not json_out and not ctx.obj.get("json"):
+        ui.text(str(val))
+
+
+@app.command("set")
+def set_command(
+    ctx: typer.Context,
+    key: Annotated[str, typer.Argument(help="Dotted configuration key, e.g. models.architect.model")],
+    value: Annotated[str, typer.Argument(help="New value")],
+    global_: GlobalFlag = False,
+    json_out: JsonFlag = False,
+    plain: PlainFlag = False,
+) -> None:
+    """Set a configuration value in project (or global) config.toml."""
+    ui = ui_from(ctx, json_out=json_out, plain=plain)
+    path = _target_path(global_)
+    set_config_value(path, key, value)
+    ui.data({"key": key, "value": value, "path": str(path)})
+    ui.ok(f"Set {key} = {value} in {path}")
+
+
+@dataclass
+class SetupAnswers:
+    provider: str
+    base_url: str | None = None
+    api_key_env: str | None = None
+    api_key: str | None = None
+    models: dict[str, str] = field(default_factory=dict)
+    sandbox_enabled: bool = False
+    approval_mode: str = "ask"
+
+
+def apply_setup(answers: SetupAnswers, *, global_dir: Path) -> None:
+    path = global_dir / CONFIG_FILE_NAME
+    if answers.base_url:
+        set_config_value(path, f"providers.{answers.provider}.type", "openai_compatible")
+        set_config_value(path, f"providers.{answers.provider}.base_url", answers.base_url)
+        if answers.api_key_env:
+            set_config_value(path, f"providers.{answers.provider}.api_key_env", answers.api_key_env)
+    if answers.api_key and answers.api_key_env:
+        store_secret(answers.api_key_env, answers.api_key, global_dir=global_dir)
+
+    for role, model in answers.models.items():
+        set_config_value(path, f"models.{role}.provider", answers.provider)
+        set_config_value(path, f"models.{role}.model", model)
+
+    set_config_value(path, "sandbox.enabled", "true" if answers.sandbox_enabled else "false")
+    set_config_value(path, "permissions.mode", answers.approval_mode)
+
+
+def _test_provider_connectivity(provider: str, base_url: str | None, api_key: str | None) -> tuple[bool, str]:
+    """Perform a lightweight test request to verify API connectivity."""
+    import httpx
+
+    url = (base_url or ("https://api.groq.com/openai/v1" if provider == "groq" else "https://api.openai.com/v1")).rstrip("/") + "/models"
+    headers = {}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    try:
+        with httpx.Client(timeout=4.0) as client:
+            resp = client.get(url, headers=headers)
+            if resp.status_code in (200, 201):
+                return True, "Connection verified (HTTP 200)"
+            return False, f"Provider returned HTTP {resp.status_code}"
+    except Exception as exc:
+        return False, str(exc)
+
+
+@app.command("setup")
+def setup_command(
+    ctx: typer.Context,
+) -> None:
+    """Interactive setup wizard for provider credentials and defaults."""
+    ui = ui_from(ctx)
+    ui.text("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+    ui.text("FORGEX Configuration Setup Wizard — Welcome!")
+    ui.text("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+    ui.text("Security & Terms Notice:")
+    ui.text(" • FORGEX operates locally and executes developer tools.")
+    ui.text(" • Reversible checkpoints are created before file edits.")
+    ui.text(" • API keys are stored with restricted permissions (0600) in ~/.forgex/.env.")
+    ui.text(" • You control permissions via mode: ask (default), auto, or safe.\n")
+
+    prov = Prompt.ask("Choose provider", choices=["groq", "openai", "local", "custom"], default="groq")
+
+    base_url = None
+    api_key_env: str | None = "FORGEX_GROQ_API_KEY"
+    api_key = None
+
+    if prov == "groq":
+        provider_name = "groq"
+        api_key = Prompt.ask("Enter your Groq API key (leave empty to skip)", password=True, default="")
+        default_model = "llama-3.3-70b-versatile"
+    elif prov == "openai":
+        provider_name = "openai_compatible"
+        api_key_env = "FORGEX_OPENAI_API_KEY"
+        api_key = Prompt.ask("Enter your OpenAI API key (leave empty to skip)", password=True, default="")
+        default_model = "gpt-4o-mini"
+    elif prov == "local":
+        provider_name = "local"
+        base_url = Prompt.ask("Enter local OpenAI-compatible endpoint", default="http://localhost:11434/v1")
+        api_key_env = None
+        default_model = Prompt.ask("Enter model name", default="llama3.1:8b")
+    else:
+        provider_name = Prompt.ask("Enter custom provider name", default="custom")
+        base_url = Prompt.ask("Enter base URL", default="http://localhost:8080/v1")
+        api_key_env = f"FORGEX_{provider_name.upper()}_API_KEY"
+        api_key = Prompt.ask("Enter API key (if required)", password=True, default="")
+        default_model = Prompt.ask("Enter default model", default="qwen2.5:14b")
+
+    # Health check verification
+    if api_key or (prov == "local" and base_url):
+        ui.text(f"Testing connectivity to {provider_name}...")
+        ok, detail = _test_provider_connectivity(provider_name, base_url, api_key)
+        if ok:
+            ui.ok(f"Provider connection verified: {detail}")
+        else:
+            ui.warn(f"Provider test: {detail} (proceeding; test with `forgex doctor --ping`)")
+
+    models = {
+        "architect": default_model,
+        "builder": default_model,
+        "expert_coder": default_model,
+        "supervisor": default_model,
+    }
+
+    if Confirm.ask("Customize models for specific agent roles?", default=False):
+        for role in ("architect", "builder", "expert_coder", "supervisor"):
+            models[role] = Prompt.ask(f"Model for {role}", default=default_model)
+
+    use_sandbox = Confirm.ask("Enable Docker sandbox for command execution?", default=False)
+    mode = Prompt.ask("Approval mode for commands and network", choices=["auto", "ask", "safe"], default="ask")
+
+    answers = SetupAnswers(
+        provider=provider_name,
+        base_url=base_url,
+        api_key_env=api_key_env,
+        api_key=api_key or None,
+        models=models,
+        sandbox_enabled=use_sandbox,
+        approval_mode=mode,
+    )
+
+    g_dir = global_config_path().parent
+    apply_setup(answers, global_dir=g_dir)
+    ui.ok(f"Setup complete! Config written to {g_dir}")