researchloop 0.1.0__tar.gz → 0.2.0__tar.gz

{researchloop-0.1.0 → researchloop-0.2.0}/.github/workflows/ci.yml

@@ -67,7 +67,11 @@ jobs:
       - name: Build SLURM test container
         run: docker build -t researchloop-slurm-test tests/docker/slurm/
 
+      - name: Build SGE test container
+        run: docker build -t researchloop-sge-test tests/docker/sge/
+
       - name: Run integration tests
-        run: uv run pytest tests/integration/ -v --tb=short -x --timeout=120
+        run: uv run pytest tests/integration/ -v --tb=short -x --timeout=180
         env:
           SLURM_TEST_IMAGE: researchloop-slurm-test
+          SGE_TEST_IMAGE: researchloop-sge-test

{researchloop-0.1.0 → researchloop-0.2.0}/CLAUDE.md

@@ -30,7 +30,7 @@ Python 3.10+, uv, asyncio throughout. Key deps: click (CLI), FastAPI (API + dash
 
 ```bash
 uv sync                              # install deps
-uv run pytest tests/ -v -m "not integration"  # unit tests (339 tests, ~3s)
+uv run pytest tests/ -v -m "not integration"  # unit tests (374 tests, ~3s)
 uv run pytest tests/integration/ -v --timeout=120  # integration tests (needs Docker)
 uv run ruff check .                  # lint
 uv run ruff format .                 # format
@@ -116,7 +116,7 @@ researchloop/
 
 ## Database
 
-SQLite with 7 tables: `studies`, `sprints`, `auto_loops`, `artifacts`, `slack_sessions`, `events`, `settings`. Schema in `db/migrations.py`. All queries in `db/queries.py` use parameterized SQL and return plain dicts.
+SQLite with 8 tables: `studies`, `sprints`, `tweaks`, `auto_loops`, `artifacts`, `slack_sessions`, `events`, `settings`. Schema in `db/migrations.py`. All queries in `db/queries.py` use parameterized SQL and return plain dicts.
 
 Key columns:
 - `sprints.webhook_token` — per-sprint token for webhook auth (generated at creation)
@@ -124,6 +124,8 @@ Key columns:
 - `sprints.metadata_json` — stores report text, has_pdf flag, heartbeat info
 - `sprints.error` — stores live progress (progress.md + output.log + tool log) during running sprints
 - `auto_loops.metadata_json` — stores loop context and job_options
+- `tweaks.sprint_id` — links tweak to parent sprint (one sprint can have many tweaks)
+- `tweaks.instruction` — the user's tweak request text
 - `settings` — key/value store for signing_key and dashboard_password_hash
 
 ## Key patterns

researchloop-0.2.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: researchloop
+Version: 0.2.0
+Summary: Automated research sprint platform for HPC clusters
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: aiosqlite<1,>=0.19
+Requires-Dist: asyncssh<3,>=2.14
+Requires-Dist: bcrypt<5,>=4.0
+Requires-Dist: click<9,>=8.0
+Requires-Dist: fastapi>=0.100
+Requires-Dist: httpx<1,>=0.24
+Requires-Dist: itsdangerous<3,>=2.1
+Requires-Dist: jinja2<4,>=3.1
+Requires-Dist: markdown<4,>=3.4
+Requires-Dist: python-multipart<1,>=0.0.6
+Requires-Dist: starlette<1
+Requires-Dist: tomli<3,>=2.0; python_version < '3.11'
+Requires-Dist: uvicorn[standard]<1,>=0.20
+Description-Content-Type: text/markdown
+
+# ResearchLoop
+
+**Run AI-automated research experiments on your HPC cluster. Monitor from anywhere.**
+
+[![CI](https://github.com/researchloop/researchloop/actions/workflows/ci.yml/badge.svg)](https://github.com/researchloop/researchloop/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/researchloop.svg)](https://pypi.org/project/researchloop/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+ResearchLoop submits AI-powered research experiments to your SLURM or SGE cluster, then reports back the results. You describe a research idea in natural language, it handles the rest: submitting the job, running a multi-step pipeline with [Claude Code](https://docs.anthropic.com/en/docs/claude-code), red-teaming the results, generating a report, and notifying you when it's done.
+
+```bash
+pip install researchloop
+
+# Submit an experiment to your cluster
+researchloop sprint run "Investigate whether batch normalization improves convergence" --study my-project
+
+# Start an auto-loop: 5 experiments, each building on the last
+researchloop loop start --study my-project --count 5 --context "Focus on improving F1 score"
+```
+
+Monitor everything from a web dashboard, Slack, or the CLI -- no need to SSH in and check on jobs.
+
+## Why ResearchLoop?
+
+If you run experiments on shared HPC clusters, you know the pain: SSH in, write a script, submit with sbatch, wait, check logs, repeat. ResearchLoop automates this loop:
+
+1. **You describe what to investigate** (via CLI, dashboard, or Slack)
+2. **ResearchLoop submits a job** to your cluster via SSH
+3. **Claude runs the full experiment** -- writes code, runs it, analyzes results
+4. **A red-team step critiques the work** and Claude fixes any issues
+5. **You get a report** with a summary, PDF, and all artifacts
+
+The **auto-loop** feature takes this further: after each experiment, Claude analyzes the results and proposes the next one. You set how many iterations, and walk away.
+
+## Get started in 5 minutes
+
+**Prerequisites:** Python 3.10+, SSH access to an HPC cluster, [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed on the cluster.
+
+### 1. Install and initialize
+
+```bash
+pip install researchloop
+researchloop init
+```
+
+### 2. Edit `researchloop.toml`
+
+```toml
+shared_secret = "pick-a-secret"
+orchestrator_url = "http://localhost:8080"
+
+[[cluster]]
+name = "my-cluster"
+host = "login.cluster.example.com"
+user = "researcher"
+key_path = "~/.ssh/id_ed25519"
+scheduler_type = "slurm"
+working_dir = "/scratch/researcher/researchloop"
+
+[cluster.job_options]
+gres = "gpu:1"
+mem = "64G"
+cpus-per-task = "8"
+
+[[study]]
+name = "my-project"
+cluster = "my-cluster"
+description = "Investigating X"
+```
+
+### 3. Start the server and run your first sprint
+
+```bash
+researchloop serve &
+researchloop connect http://localhost:8080
+researchloop sprint run "Try approach X on dataset Y" --study my-project
+```
+
+That's it. ResearchLoop SSHes to your cluster, submits the job, and you can monitor progress from the dashboard at `http://localhost:8080/dashboard/`.
+
+## Three ways to interact
+
+### Web dashboard
+
+Browse to `/dashboard/` to see all your studies, sprints, and loops. Submit new sprints, start loops with custom GPU/memory settings, refresh live status from the cluster, and read reports -- all from the browser.
+
+### Slack bot
+
+Chat with the bot to start sprints, check status, or discuss research ideas. The bot maintains conversation context across a thread, so you can have a back-and-forth about what to try next.
+
+```
+You: What should I investigate next based on the results from sp-a3f7b2?
+Bot: Based on the findings, I'd suggest... [ACTION: sprint_run {"study": "my-project", "idea": "..."}]
+```
+
+See the [Slack setup guide](https://researchloop.github.io/researchloop/slack/) for configuration.
+
+### CLI
+
+```bash
+researchloop sprint run "idea" --study my-project   # Submit a sprint
+researchloop sprint list                             # List recent sprints
+researchloop sprint show sp-a3f7b2                   # View details
+researchloop loop start --study my-project --count 5 # Auto-loop
+researchloop loop stop loop-b4e1c9                   # Stop a loop
+```
+
+## Customizing your studies
+
+Each study can have its own context, cluster settings, and configuration:
+
+```toml
+[[study]]
+name = "sae-research"
+cluster = "my-cluster"
+max_sprint_duration_hours = 12
+red_team_max_rounds = 2
+allow_loop = true
+
+# Tell Claude what this study is about and how to approach it
+context = """
+You are researching sparse autoencoder architectures.
+Always train for 200M samples. Use batch size 1024.
+Validate on the variation models listed in ~/reference/models.txt.
+"""
+
+# Or point to a file with detailed instructions
+claude_md_path = "./studies/sae-research/CLAUDE.md"
+
+# Override GPU/memory for this study
+[study.job_options]
+gres = "gpu:a100:2"
+mem = "128G"
+```
+
+The context hierarchy is: **global** > **cluster** > **study**. All levels are merged and included in every sprint's prompt.
+
+## Deployment
+
+For production, deploy the orchestrator as a Docker container on Fly.io, Railway, or any platform that supports persistent volumes:
+
+```bash
+pip install researchloop
+# See deployment guide for Docker/Fly.io setup
+```
+
+Full deployment guide: [researchloop.github.io/researchloop/deployment](https://researchloop.github.io/researchloop/deployment/)
+
+## Documentation
+
+Full docs at **[researchloop.github.io/researchloop](https://researchloop.github.io/researchloop/)**, including:
+
+- [Configuration reference](https://researchloop.github.io/researchloop/configuration/) -- all TOML options and environment variables
+- [Deployment guide](https://researchloop.github.io/researchloop/deployment/) -- Docker, Fly.io, SSH key setup
+- [Dashboard guide](https://researchloop.github.io/researchloop/dashboard/) -- web UI features and authentication
+- [Slack integration](https://researchloop.github.io/researchloop/slack/) -- setup, commands, conversational mode
+- [CLI reference](https://researchloop.github.io/researchloop/cli/) -- all commands with examples
+- [Security](https://researchloop.github.io/researchloop/security/) -- authentication, CSRF, webhook tokens
+- [Development](https://researchloop.github.io/researchloop/development/) -- contributing, testing, architecture
+
+## Contributing
+
+```bash
+git clone https://github.com/researchloop/researchloop.git
+cd researchloop
+uv sync
+uv run pytest tests/ -m "not integration"   # Unit tests
+uv run ruff check . && uv run pyright researchloop/  # Lint + type check
+```
+
+Integration tests run against a real SLURM scheduler in Docker -- see [development guide](https://researchloop.github.io/researchloop/development/).
+
+## License
+
+MIT

researchloop-0.2.0/README.md

@@ -0,0 +1,178 @@
+# ResearchLoop
+
+**Run AI-automated research experiments on your HPC cluster. Monitor from anywhere.**
+
+[![CI](https://github.com/researchloop/researchloop/actions/workflows/ci.yml/badge.svg)](https://github.com/researchloop/researchloop/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/researchloop.svg)](https://pypi.org/project/researchloop/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+ResearchLoop submits AI-powered research experiments to your SLURM or SGE cluster, then reports back the results. You describe a research idea in natural language, it handles the rest: submitting the job, running a multi-step pipeline with [Claude Code](https://docs.anthropic.com/en/docs/claude-code), red-teaming the results, generating a report, and notifying you when it's done.
+
+```bash
+pip install researchloop
+
+# Submit an experiment to your cluster
+researchloop sprint run "Investigate whether batch normalization improves convergence" --study my-project
+
+# Start an auto-loop: 5 experiments, each building on the last
+researchloop loop start --study my-project --count 5 --context "Focus on improving F1 score"
+```
+
+Monitor everything from a web dashboard, Slack, or the CLI -- no need to SSH in and check on jobs.
+
+## Why ResearchLoop?
+
+If you run experiments on shared HPC clusters, you know the pain: SSH in, write a script, submit with sbatch, wait, check logs, repeat. ResearchLoop automates this loop:
+
+1. **You describe what to investigate** (via CLI, dashboard, or Slack)
+2. **ResearchLoop submits a job** to your cluster via SSH
+3. **Claude runs the full experiment** -- writes code, runs it, analyzes results
+4. **A red-team step critiques the work** and Claude fixes any issues
+5. **You get a report** with a summary, PDF, and all artifacts
+
+The **auto-loop** feature takes this further: after each experiment, Claude analyzes the results and proposes the next one. You set how many iterations, and walk away.
+
+## Get started in 5 minutes
+
+**Prerequisites:** Python 3.10+, SSH access to an HPC cluster, [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed on the cluster.
+
+### 1. Install and initialize
+
+```bash
+pip install researchloop
+researchloop init
+```
+
+### 2. Edit `researchloop.toml`
+
+```toml
+shared_secret = "pick-a-secret"
+orchestrator_url = "http://localhost:8080"
+
+[[cluster]]
+name = "my-cluster"
+host = "login.cluster.example.com"
+user = "researcher"
+key_path = "~/.ssh/id_ed25519"
+scheduler_type = "slurm"
+working_dir = "/scratch/researcher/researchloop"
+
+[cluster.job_options]
+gres = "gpu:1"
+mem = "64G"
+cpus-per-task = "8"
+
+[[study]]
+name = "my-project"
+cluster = "my-cluster"
+description = "Investigating X"
+```
+
+### 3. Start the server and run your first sprint
+
+```bash
+researchloop serve &
+researchloop connect http://localhost:8080
+researchloop sprint run "Try approach X on dataset Y" --study my-project
+```
+
+That's it. ResearchLoop SSHes to your cluster, submits the job, and you can monitor progress from the dashboard at `http://localhost:8080/dashboard/`.
+
+## Three ways to interact
+
+### Web dashboard
+
+Browse to `/dashboard/` to see all your studies, sprints, and loops. Submit new sprints, start loops with custom GPU/memory settings, refresh live status from the cluster, and read reports -- all from the browser.
+
+### Slack bot
+
+Chat with the bot to start sprints, check status, or discuss research ideas. The bot maintains conversation context across a thread, so you can have a back-and-forth about what to try next.
+
+```
+You: What should I investigate next based on the results from sp-a3f7b2?
+Bot: Based on the findings, I'd suggest... [ACTION: sprint_run {"study": "my-project", "idea": "..."}]
+```
+
+See the [Slack setup guide](https://researchloop.github.io/researchloop/slack/) for configuration.
+
+### CLI
+
+```bash
+researchloop sprint run "idea" --study my-project   # Submit a sprint
+researchloop sprint list                             # List recent sprints
+researchloop sprint show sp-a3f7b2                   # View details
+researchloop loop start --study my-project --count 5 # Auto-loop
+researchloop loop stop loop-b4e1c9                   # Stop a loop
+```
+
+## Customizing your studies
+
+Each study can have its own context, cluster settings, and configuration:
+
+```toml
+[[study]]
+name = "sae-research"
+cluster = "my-cluster"
+max_sprint_duration_hours = 12
+red_team_max_rounds = 2
+allow_loop = true
+
+# Tell Claude what this study is about and how to approach it
+context = """
+You are researching sparse autoencoder architectures.
+Always train for 200M samples. Use batch size 1024.
+Validate on the variation models listed in ~/reference/models.txt.
+"""
+
+# Or point to a file with detailed instructions
+claude_md_path = "./studies/sae-research/CLAUDE.md"
+
+# Override GPU/memory for this study
+[study.job_options]
+gres = "gpu:a100:2"
+mem = "128G"
+```
+
+The context hierarchy is: **global** > **cluster** > **study**. All levels are merged and included in every sprint's prompt.
+
+## Deployment
+
+For production, deploy the orchestrator as a Docker container on Fly.io, Railway, or any platform that supports persistent volumes:
+
+```bash
+pip install researchloop
+# See deployment guide for Docker/Fly.io setup
+```
+
+Full deployment guide: [researchloop.github.io/researchloop/deployment](https://researchloop.github.io/researchloop/deployment/)
+
+## Documentation
+
+Full docs at **[researchloop.github.io/researchloop](https://researchloop.github.io/researchloop/)**, including:
+
+- [Configuration reference](https://researchloop.github.io/researchloop/configuration/) -- all TOML options and environment variables
+- [Deployment guide](https://researchloop.github.io/researchloop/deployment/) -- Docker, Fly.io, SSH key setup
+- [Dashboard guide](https://researchloop.github.io/researchloop/dashboard/) -- web UI features and authentication
+- [Slack integration](https://researchloop.github.io/researchloop/slack/) -- setup, commands, conversational mode
+- [CLI reference](https://researchloop.github.io/researchloop/cli/) -- all commands with examples
+- [Security](https://researchloop.github.io/researchloop/security/) -- authentication, CSRF, webhook tokens
+- [Development](https://researchloop.github.io/researchloop/development/) -- contributing, testing, architecture
+
+## Contributing
+
+```bash
+git clone https://github.com/researchloop/researchloop.git
+cd researchloop
+uv sync
+uv run pytest tests/ -m "not integration"   # Unit tests
+uv run ruff check . && uv run pyright researchloop/  # Lint + type check
+```
+
+Integration tests run against a real SLURM scheduler in Docker -- see [development guide](https://researchloop.github.io/researchloop/development/).
+
+## License
+
+MIT

{researchloop-0.1.0 → researchloop-0.2.0}/docs/deployment.md

@@ -20,8 +20,7 @@ RUN curl -fsSL https://claude.ai/install.sh | bash
 # Install researchloop
 COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
 RUN uv venv /app/.venv && \
-    uv pip install --python /app/.venv/bin/python --no-cache \
-    "researchloop @ git+https://github.com/chanind/researchloop.git"
+    uv pip install --python /app/.venv/bin/python --no-cache researchloop
 
 WORKDIR /app
 

{researchloop-0.1.0 → researchloop-0.2.0}/docs/development.md

@@ -3,7 +3,7 @@
 ## Setup
 
 ```bash
-git clone https://github.com/chanind/researchloop.git
+git clone https://github.com/researchloop/researchloop.git
 cd researchloop
 uv sync
 ```

{researchloop-0.1.0 → researchloop-0.2.0}/docs/getting-started.md

@@ -3,24 +3,13 @@
 ## Prerequisites
 
 - **Python 3.10+**
-- **[uv](https://docs.astral.sh/uv/)** (recommended) or pip
 - **SSH access** to an HPC cluster with SLURM or SGE
 - **[Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)** installed and authenticated on the HPC cluster
 
 ## Installation
 
-### From GitHub
-
-```bash
-pip install git+https://github.com/chanind/researchloop.git
-```
-
-### For development
-
 ```bash
-git clone https://github.com/chanind/researchloop.git
-cd researchloop
-uv sync
+pip install researchloop
 ```
 
 ## Initialize a project

{researchloop-0.1.0 → researchloop-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "researchloop"
-version = "0.1.0"
+version = "0.2.0"
 description = "Automated research sprint platform for HPC clusters"
 readme = "README.md"
 license = {text = "MIT"}
@@ -18,7 +18,8 @@ classifiers = [
 ]
 dependencies = [
     "click>=8.0,<9",
-    "fastapi>=0.100,<1",
+    "fastapi>=0.100",
+    "starlette<1",
     "uvicorn[standard]>=0.20,<1",
     "jinja2>=3.1,<4",
     "aiosqlite>=0.19,<1",

researchloop-0.2.0/researchloop/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

{researchloop-0.1.0 → researchloop-0.2.0}/researchloop/cli.py

@@ -1136,3 +1136,185 @@ async def _cluster_check(config_path: str | None, cluster_name: str | None) -> N
 def cluster_check(ctx: click.Context, name: str | None) -> None:
     """Check cluster connectivity."""
     run_async(_cluster_check(ctx.obj.get("config_path"), name))
+
+
+# ===================================================================
+# Slack testing commands
+# ===================================================================
+
+
+@cli.command("test-slack")
+@click.argument("message")
+@click.option(
+    "--url",
+    default="http://localhost:8080",
+    show_default=True,
+    help="Orchestrator URL to send the event to",
+)
+@click.option(
+    "--signing-secret",
+    default="test_signing_secret",
+    show_default=True,
+    help="Slack signing secret for signature generation",
+)
+@click.option("--user", default="U_TEST", show_default=True, help="Slack user ID")
+@click.option("--channel", default="C_TEST", show_default=True, help="Slack channel ID")
+@click.option(
+    "--thread-ts",
+    default=None,
+    help="Thread timestamp (for threaded replies)",
+)
+def test_slack(
+    message: str,
+    url: str,
+    signing_secret: str,
+    user: str,
+    channel: str,
+    thread_ts: str | None,
+) -> None:
+    """Send a signed Slack event to the orchestrator for testing.
+
+    Example::
+
+        researchloop test-slack "help" --url http://localhost:8080
+
+        researchloop test-slack "sprint run my-study some idea" \\
+            --signing-secret abc123
+    """
+    import hashlib as _hashlib
+    import hmac as _hmac
+    import time as _time
+    import uuid as _uuid
+
+    ts = thread_ts or f"{int(_time.time())}.000001"
+
+    event_id = f"Ev{_uuid.uuid4().hex[:10].upper()}"
+    payload: dict[str, Any] = {
+        "type": "event_callback",
+        "event_id": event_id,
+        "event": {
+            "type": "message",
+            "text": message,
+            "user": user,
+            "channel": channel,
+            "channel_type": "channel",
+            "ts": ts,
+        },
+    }
+    if thread_ts:
+        payload["event"]["thread_ts"] = thread_ts
+
+    body = json.dumps(payload).encode()
+
+    timestamp = str(int(_time.time()))
+    basestring = f"v0:{timestamp}:{body.decode('utf-8')}"
+    sig = (
+        "v0="
+        + _hmac.new(
+            signing_secret.encode(),
+            basestring.encode(),
+            _hashlib.sha256,
+        ).hexdigest()
+    )
+
+    headers = {
+        "Content-Type": "application/json",
+        "X-Slack-Request-Timestamp": timestamp,
+        "X-Slack-Signature": sig,
+    }
+
+    target = url.rstrip("/") + "/api/slack/events"
+    click.echo(f"Sending event to {target}")
+    click.echo(f"  User   : {user}")
+    click.echo(f"  Channel: {channel}")
+    click.echo(f"  Text   : {message}")
+    if thread_ts:
+        click.echo(f"  Thread : {thread_ts}")
+    click.echo()
+
+    try:
+        resp = httpx.post(target, content=body, headers=headers, timeout=10)
+        click.echo(click.style(f"Response [{resp.status_code}]:", bold=True))
+        try:
+            click.echo(json.dumps(resp.json(), indent=2))
+        except Exception:
+            click.echo(resp.text)
+    except httpx.ConnectError:
+        raise click.ClickException(f"Cannot connect to {target}")
+    except httpx.TimeoutException:
+        raise click.ClickException(f"Request timed out: {target}")
+
+
+@cli.command("mock-slack")
+@click.option(
+    "--port",
+    default=9876,
+    show_default=True,
+    type=int,
+    help="Port to run the mock server on",
+)
+@click.option(
+    "--host",
+    default="127.0.0.1",
+    show_default=True,
+    help="Host to bind to",
+)
+@click.option(
+    "--target-url",
+    default="http://localhost:8080",
+    show_default=True,
+    help="Orchestrator URL for the /send-event endpoint",
+)
+@click.option(
+    "--signing-secret",
+    default="mock_signing_secret",
+    show_default=True,
+    help="Signing secret for generated events",
+)
+def mock_slack(
+    port: int,
+    host: str,
+    target_url: str,
+    signing_secret: str,
+) -> None:
+    """Start a mock Slack API server for local testing.
+
+    This server captures all outbound Slack API calls (postMessage,
+    files.upload) and exposes inspection endpoints.
+
+    Example::
+
+        researchloop mock-slack --port 9876
+
+    Then set the environment variable before starting the orchestrator::
+
+        export RESEARCHLOOP_SLACK_API_URL=http://localhost:9876/api
+        researchloop serve
+    """
+    import uvicorn
+
+    from researchloop.testing.slack_mock import create_mock_slack_app
+
+    app = create_mock_slack_app(
+        target_url=target_url,
+        signing_secret=signing_secret,
+    )
+
+    api_url = f"http://{host}:{port}/api"
+    click.echo()
+    click.echo(click.style("Mock Slack API", fg="cyan", bold=True))
+    click.echo()
+    click.echo(f"  Running at: {api_url}")
+    click.echo()
+    click.echo(
+        "  Set "
+        + click.style(f"RESEARCHLOOP_SLACK_API_URL={api_url}", bold=True)
+        + " to redirect Slack calls"
+    )
+    click.echo()
+    click.echo(f"  View captured messages: http://{host}:{port}/captured")
+    click.echo(f"  Clear captured:         POST http://{host}:{port}/clear")
+    click.echo(f"  Send test event:        POST http://{host}:{port}/send-event")
+    click.echo()
+
+    uvicorn.run(app, host=host, port=port)