bob-dev 0.3.0__tar.gz → 0.4.4__tar.gz

{bob_dev-0.3.0 → bob_dev-0.4.4}/PKG-INFO

@@ -1,11 +1,25 @@
 Metadata-Version: 2.4
 Name: bob-dev
-Version: 0.3.0
+Version: 0.4.4
 Summary: An AI developer to write code for you
 Author-email: Samuel Pereira dos Santos <samuelsantosdev@gmail.com>
-Requires-Python: >=3.12.10
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: faiss-cpu>=1.9.0
+Requires-Dist: langchain>=0.3.0
+Requires-Dist: langchain-community>=0.3.0
+Requires-Dist: langchain-openai>=0.2.0
+Requires-Dist: langchain-text-splitters>=0.3.0
+Requires-Dist: openai>=1.50.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: InquirerPy>=0.3.4
+Requires-Dist: pydantic>=2.0
+Requires-Dist: atlassian-python-api>=3.41.0
+Requires-Dist: python-gitlab>=4.4.0
+Requires-Dist: summa>=1.2.0
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: rich>=13.0.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
@@ -13,7 +27,7 @@ Dynamic: license-file
 
 # BOB Dev
 
-**BOB Dev** is an AI-powered developer workflow CLI that bridges a task requirements, your codebase, and Claude Code.
+**BOB Dev** is an AI-powered developer workflow CLI that bridges task requirements, your codebase, and Claude Code.
 
 ![BOB-Dev Banner](https://github.com/samuelsantosdev/bob-dev/blob/main/assets/banner.png)
 
@@ -21,16 +35,17 @@ Given a task ID (Jira or GitLab) it will:
 
 1. **Fetch** the task title, description, and fix versions from Jira or GitLab.
 2. **Read** your project's Markdown documentation to build rich LLM context.
-3. **Generate** a precise Claude Code prompt (via GROK or OpenAI), including project-framework context, implementation steps, and test scenarios.
-4. **Analyse** the prompt for ambiguities and security concerns.
-5. **Select** (optionally) a Claude Code agent to run the implementation.
-6. **Execute** the prompt with the Claude Code CLI (optional – you can review first).
+3. **Detect** the project framework (Django, React, FastAPI, Spring Boot, and more).
+4. **Generate** a precise Claude Code prompt (via GROK or OpenAI), including framework context, implementation steps, and test scenarios.
+5. **Analyse** the prompt for ambiguities and security concerns.
+6. **Select** (optionally) a Claude Code agent to run the implementation.
+7. **Execute** the prompt with the Claude Code CLI (optional — you can review and edit first).
 
 ---
 
 ## Requirements
 
-- Python 3.12+
+- Python 3.11+
 - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and available on `$PATH` as `claude`
 - A **Jira Cloud** account with an [API token](https://id.atlassian.com/manage-profile/security/api-tokens) **or** a **GitLab** account with a [personal access token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)
 - An [xAI / GROK](https://console.x.ai/) **or** [OpenAI](https://platform.openai.com/) API key
@@ -53,22 +68,42 @@ Run the interactive setup wizard the first time:
 bob-dev --configure
 ```
 
-This will prompt for your LLM API key, task manager (Jira or GitLab) credentials, and Claude Code API key.
+This prompts for your LLM backend, API key, task manager (Jira or GitLab), and their credentials. All values are saved to `~/.bob_dev/.env`.
 
 ### Environment variables
 
+**Required**
+
+| Variable | Options | Description |
+|----------|---------|-------------|
+| `AGENT` | `GROK` (default) / `OPENAI` | LLM backend |
+| `GROK_API_KEY` | — | xAI / GROK secret key (required if `AGENT=GROK`) |
+| `OPENAI_API_KEY` | — | OpenAI secret key (required if `AGENT=OPENAI`) |
+| `TASK_MANAGER` | `JIRA` (default) / `GITLAB` | Task management system |
+
+**Jira** (`TASK_MANAGER=JIRA`)
+
 | Variable | Description |
 |----------|-------------|
-| `AGENT` | LLM backend: `GROK` (default) or `OPENAI` |
-| `GROK_API_KEY` | xAI / GROK secret key |
-| `OPENAI_API_KEY` | OpenAI secret key |
-| `TASK_MANAGER` | Task manager: `JIRA` (default) or `GITLAB` |
 | `JIRA_URL` | e.g. `https://your-org.atlassian.net` |
 | `JIRA_EMAIL` | Atlassian account e-mail |
 | `JIRA_API_TOKEN` | Atlassian API token |
+
+**GitLab** (`TASK_MANAGER=GITLAB`)
+
+| Variable | Description |
+|----------|-------------|
 | `GITLAB_URL` | e.g. `https://gitlab.com` |
 | `GITLAB_API_TOKEN` | GitLab personal access token |
 
+**Optional**
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MAX_FILES` | `30` | Max number of Markdown files read for project context |
+| `MAX_CHARS` | `40000` | Max characters of Markdown content fed to the LLM |
+| `MAX_SUMMARY_WORDS` | `2000` | Max words when auto-summarising the project README |
+
 ---
 
 ## Usage
@@ -83,9 +118,9 @@ bob-dev --task_id 42 --path /path/to/your/repo
 
 | Flag | Description |
 |------|-------------|
-| `--task_id` | Task ID to process — Jira key (`PROJ-123`) or GitLab issue IID (`42`) |
+| `--task_id` | Task ID — Jira key (`PROJ-123`) or GitLab issue IID (`42`) |
 | `--path` | Path to the target repository (default: current directory) |
-| `--agent` | LLM backend: `GROK` or `OPENAI` (default: value of `AGENT` in `.env`) |
+| `--agent` | LLM backend: `GROK` or `OPENAI` (overrides the `AGENT` env var) |
 | `--configure` | Run the interactive configuration wizard |
 
 ---
@@ -95,6 +130,7 @@ bob-dev --task_id 42 --path /path/to/your/repo
 ```
 src/bob_dev/
 ├── cli.py                  # Entry point & main workflow orchestration
+├── settings.py             # Environment variable loading and validation
 ├── services/
 │   ├── terminal.py         # ANSI colours, print helpers, spinner animation
 │   ├── jira.py             # Jira API connection + ADF-to-text parsing
@@ -105,6 +141,22 @@ src/bob_dev/
 │   └── config.py           # .env management + credential validation
 └── constants/
     └── frameworks.py       # Known framework names used for auto-detection
+
+tests/
+├── test_cli.py
+├── test_config.py
+├── test_jira.py
+├── test_llm.py
+├── test_project.py
+└── test_terminal.py
+```
+
+---
+
+## Running tests
+
+```bash
+pytest tests/
 ```
 
 ---
@@ -115,6 +167,7 @@ src/bob_dev/
 |--------|---------|
 | Red    | Errors that stop execution |
 | Green  | Success messages |
+| Yellow | Warnings |
 | Plain  | Informational / default output |
 
 ---

bob_dev-0.3.0/src/bob_dev.egg-info/PKG-INFO → bob_dev-0.4.4/README.md

@@ -1,19 +1,6 @@
-Metadata-Version: 2.4
-Name: bob-dev
-Version: 0.3.0
-Summary: An AI developer to write code for you
-Author-email: Samuel Pereira dos Santos <samuelsantosdev@gmail.com>
-Requires-Python: >=3.12.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Provides-Extra: dev
-Requires-Dist: pytest>=8.0; extra == "dev"
-Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
-Dynamic: license-file
-
 # BOB Dev
 
-**BOB Dev** is an AI-powered developer workflow CLI that bridges a task requirements, your codebase, and Claude Code.
+**BOB Dev** is an AI-powered developer workflow CLI that bridges task requirements, your codebase, and Claude Code.
 
 ![BOB-Dev Banner](https://github.com/samuelsantosdev/bob-dev/blob/main/assets/banner.png)
 
@@ -21,16 +8,17 @@ Given a task ID (Jira or GitLab) it will:
 
 1. **Fetch** the task title, description, and fix versions from Jira or GitLab.
 2. **Read** your project's Markdown documentation to build rich LLM context.
-3. **Generate** a precise Claude Code prompt (via GROK or OpenAI), including project-framework context, implementation steps, and test scenarios.
-4. **Analyse** the prompt for ambiguities and security concerns.
-5. **Select** (optionally) a Claude Code agent to run the implementation.
-6. **Execute** the prompt with the Claude Code CLI (optional – you can review first).
+3. **Detect** the project framework (Django, React, FastAPI, Spring Boot, and more).
+4. **Generate** a precise Claude Code prompt (via GROK or OpenAI), including framework context, implementation steps, and test scenarios.
+5. **Analyse** the prompt for ambiguities and security concerns.
+6. **Select** (optionally) a Claude Code agent to run the implementation.
+7. **Execute** the prompt with the Claude Code CLI (optional — you can review and edit first).
 
 ---
 
 ## Requirements
 
-- Python 3.12+
+- Python 3.11+
 - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and available on `$PATH` as `claude`
 - A **Jira Cloud** account with an [API token](https://id.atlassian.com/manage-profile/security/api-tokens) **or** a **GitLab** account with a [personal access token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)
 - An [xAI / GROK](https://console.x.ai/) **or** [OpenAI](https://platform.openai.com/) API key
@@ -53,22 +41,42 @@ Run the interactive setup wizard the first time:
 bob-dev --configure
 ```
 
-This will prompt for your LLM API key, task manager (Jira or GitLab) credentials, and Claude Code API key.
+This prompts for your LLM backend, API key, task manager (Jira or GitLab), and their credentials. All values are saved to `~/.bob_dev/.env`.
 
 ### Environment variables
 
+**Required**
+
+| Variable | Options | Description |
+|----------|---------|-------------|
+| `AGENT` | `GROK` (default) / `OPENAI` | LLM backend |
+| `GROK_API_KEY` | — | xAI / GROK secret key (required if `AGENT=GROK`) |
+| `OPENAI_API_KEY` | — | OpenAI secret key (required if `AGENT=OPENAI`) |
+| `TASK_MANAGER` | `JIRA` (default) / `GITLAB` | Task management system |
+
+**Jira** (`TASK_MANAGER=JIRA`)
+
 | Variable | Description |
 |----------|-------------|
-| `AGENT` | LLM backend: `GROK` (default) or `OPENAI` |
-| `GROK_API_KEY` | xAI / GROK secret key |
-| `OPENAI_API_KEY` | OpenAI secret key |
-| `TASK_MANAGER` | Task manager: `JIRA` (default) or `GITLAB` |
 | `JIRA_URL` | e.g. `https://your-org.atlassian.net` |
 | `JIRA_EMAIL` | Atlassian account e-mail |
 | `JIRA_API_TOKEN` | Atlassian API token |
+
+**GitLab** (`TASK_MANAGER=GITLAB`)
+
+| Variable | Description |
+|----------|-------------|
 | `GITLAB_URL` | e.g. `https://gitlab.com` |
 | `GITLAB_API_TOKEN` | GitLab personal access token |
 
+**Optional**
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MAX_FILES` | `30` | Max number of Markdown files read for project context |
+| `MAX_CHARS` | `40000` | Max characters of Markdown content fed to the LLM |
+| `MAX_SUMMARY_WORDS` | `2000` | Max words when auto-summarising the project README |
+
 ---
 
 ## Usage
@@ -83,9 +91,9 @@ bob-dev --task_id 42 --path /path/to/your/repo
 
 | Flag | Description |
 |------|-------------|
-| `--task_id` | Task ID to process — Jira key (`PROJ-123`) or GitLab issue IID (`42`) |
+| `--task_id` | Task ID — Jira key (`PROJ-123`) or GitLab issue IID (`42`) |
 | `--path` | Path to the target repository (default: current directory) |
-| `--agent` | LLM backend: `GROK` or `OPENAI` (default: value of `AGENT` in `.env`) |
+| `--agent` | LLM backend: `GROK` or `OPENAI` (overrides the `AGENT` env var) |
 | `--configure` | Run the interactive configuration wizard |
 
 ---
@@ -95,6 +103,7 @@ bob-dev --task_id 42 --path /path/to/your/repo
 ```
 src/bob_dev/
 ├── cli.py                  # Entry point & main workflow orchestration
+├── settings.py             # Environment variable loading and validation
 ├── services/
 │   ├── terminal.py         # ANSI colours, print helpers, spinner animation
 │   ├── jira.py             # Jira API connection + ADF-to-text parsing
@@ -105,6 +114,22 @@ src/bob_dev/
 │   └── config.py           # .env management + credential validation
 └── constants/
     └── frameworks.py       # Known framework names used for auto-detection
+
+tests/
+├── test_cli.py
+├── test_config.py
+├── test_jira.py
+├── test_llm.py
+├── test_project.py
+└── test_terminal.py
+```
+
+---
+
+## Running tests
+
+```bash
+pytest tests/
 ```
 
 ---
@@ -115,6 +140,7 @@ src/bob_dev/
 |--------|---------|
 | Red    | Errors that stop execution |
 | Green  | Success messages |
+| Yellow | Warnings |
 | Plain  | Informational / default output |
 
 ---

bob_dev-0.4.4/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bob-dev"
+version = "0.4.4"
+description = "An AI developer to write code for you"
+readme = "README.md"
+authors = [{ name="Samuel Pereira dos Santos", email="samuelsantosdev@gmail.com" }]
+requires-python = ">=3.11"
+dependencies = [
+    "faiss-cpu>=1.9.0",
+    "langchain>=0.3.0",
+    "langchain-community>=0.3.0",
+    "langchain-openai>=0.2.0",
+    "langchain-text-splitters>=0.3.0",
+    "openai>=1.50.0",
+    "python-dotenv>=1.0.0",
+    "InquirerPy>=0.3.4",
+    "pydantic>=2.0",
+    "atlassian-python-api>=3.41.0",
+    "python-gitlab>=4.4.0",
+    "summa>=1.2.0",
+    "beautifulsoup4>=4.12.0",
+    "rich>=13.0.0",
+]
+
+[project.scripts]
+bob-dev = "bob_dev.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+filterwarnings = [
+    "ignore:.*langchain-community.*:DeprecationWarning",
+]

{bob_dev-0.3.0 → bob_dev-0.4.4}/src/bob_dev/cli.py

@@ -13,6 +13,7 @@ Workflow
 
 Usage
 -----
+    bob-dev                                   # interactive shell (REPL)
     bob-dev --task_id PROJ-123 --path /path/to/repo
     bob-dev --configure
 
@@ -33,7 +34,6 @@ import sys
 import argparse
 import asyncio
 from pathlib import Path
-from time import sleep
 
 from InquirerPy import inquirer
 from dotenv import load_dotenv
@@ -43,6 +43,7 @@ from .services.terminal import (
     RESET,
     print_error,
     print_info,
+    print_markdown,
     print_step,
     print_success,
     print_warn,
@@ -51,9 +52,11 @@ from .services.terminal import (
 )
 from .services.jira import get_jira_task
 from .services.gitlab import get_gitlab_task
-from .services.llm import analyse_prompt, llm_model, prompt_claude_code, review_prompt
+from .services.llm import analyse_prompt, chat_completion, llm_model, review_prompt
 from .services.project import build_md_context, identify_framework
 from .services.config import check_configuration, update_env_file
+from .services.langchain_service import run_langchain_chain
+from .services.rag import retrieve_rag_context
 
 # ---------------------------------------------------------------------------
 # Module-level configuration
@@ -88,7 +91,7 @@ MAX_SUMMARY_WORDS = int(os.environ.get("MAX_SUMMARY_WORDS", 2000))
 # ---------------------------------------------------------------------------
 
 def main() -> None:
-    """Parse CLI arguments and orchestrate the four-step workflow."""
+    """Parse CLI arguments; run one-shot task workflow, --configure, or the REPL."""
 
     parser = argparse.ArgumentParser(
         prog="bob-dev",
@@ -96,7 +99,10 @@ def main() -> None:
     )
     parser.add_argument(
         "--task_id", type=str,
-        help="Task ID to process (e.g. PROJ-123 for Jira or 42 for GitLab).",
+        help=(
+            "Task ID to process (e.g. PROJ-123 for Jira or 42 for GitLab). "
+            "Omit to start the interactive shell instead."
+        ),
     )
     parser.add_argument(
         "--path", type=str, default="./",
@@ -117,13 +123,18 @@ def main() -> None:
         _run_configure()
         sys.exit(0)
 
-    # ── Require task_id for normal workflow ──────────────────────────────────
+    # ── No task_id on the command line: drop into the interactive REPL ──────
     if not args.task_id:
-        print_error("Task ID is required. Use --task_id PROJ-123 for Jira or 42 for GitLab.")
-        sys.exit(1)
+        _run_repl(args.agent.upper(), args.path)
+        sys.exit(0)
+
+    _run_one_shot(args.task_id, args.path, args.agent.upper())
 
-    task_id = args.task_id.strip().upper()
-    agent   = args.agent.upper()
+
+def _run_one_shot(task_id_raw: str, path: str, agent: str) -> None:
+    """Run the full fetch → context → RAG → prompt → execute workflow once."""
+
+    task_id = task_id_raw.strip().upper()
 
     # ── Validate credentials before making any API calls ────────────────────
     if TASK_MANAGER == "JIRA" and not all([JIRA_URL, JIRA_EMAIL, JIRA_API_TOKEN]):
@@ -144,7 +155,7 @@ def main() -> None:
 
     # ── Resolve and validate the repository path ─────────────────────────────
     global REPO_BASE_PATH
-    REPO_BASE_PATH = Path(args.path).resolve()
+    REPO_BASE_PATH = Path(path).resolve()
 
     if not REPO_BASE_PATH.exists() or not REPO_BASE_PATH.is_dir():
         print_error(f"Invalid project path: {REPO_BASE_PATH}")
@@ -156,7 +167,7 @@ def main() -> None:
     print()
 
     # ── Step 1 – Fetch task ─────────────────────────────────────────────
-    print_step("[1/4]", f"Fetching {TASK_MANAGER} task {task_id} …")
+    print_step("[1/5]", f"Fetching {TASK_MANAGER} task {task_id} …")
 
     if TASK_MANAGER == "JIRA":
         task = asyncio.run(run_with_spinner(
@@ -182,16 +193,14 @@ def main() -> None:
         sys.exit(1)
 
 
-    # ── Step 2 – Read project docs & generate prompt ─────────────────────────
-    print_step("[2/4]", f"Generating Claude Code prompt via {agent} ({llm_model(agent)}) …")
+    # ── Step 2 – Read project docs ───────────────────────────────────────────
+    print_step("[2/5]", "Reading project documentation …")
 
-    # Collect Markdown context (blocking I/O) inside the spinner thread.
     md_context = asyncio.run(run_with_spinner(
         build_md_context, REPO_BASE_PATH, MAX_SUMMARY_WORDS,
         label="Reading project docs",
     ))
 
-    # Framework detection is fast – no spinner needed.
     try:
         framework = identify_framework(md_context)
         print_success(f"Detected framework : {framework}")
@@ -199,14 +208,29 @@ def main() -> None:
         print_warn(str(exc))
         framework = "the project"
 
+    # ── Step 3 – Build RAG index from framework documentation ────────────────
+    print_step("[3/5]", f"Building RAG index for {framework} …")
+
+    rag_context = asyncio.run(run_with_spinner(
+        retrieve_rag_context,
+        framework, acceptance_criteria,
+        agent, GROK_API_KEY, OPENAI_API_KEY,
+        label="Building RAG context",
+    ))
+
+    if rag_context:
+        print_success("RAG context ready.")
+    else:
+        print_warn(f"No documentation mapped for '{framework}' — RAG context skipped.")
+    print()
+
     execute_prompt = False
     while execute_prompt is False:
         prompt_md = asyncio.run(run_with_spinner(
-            prompt_claude_code,
-            acceptance_criteria, md_context, framework,
-            agent, GROK_API_KEY, OPENAI_API_KEY,
+            run_langchain_chain,
+            acceptance_criteria, md_context, task_id, framework,
+            agent, GROK_API_KEY, OPENAI_API_KEY, rag_context,
             label="Generating prompt",
-            task_meta=task,
         ))
 
         if not prompt_md.strip():
@@ -216,8 +240,8 @@ def main() -> None:
         print_success("Prompt generated.")
         print()
 
-        # ── Step 3 – Analyse the prompt ──────────────────────────────────────────
-        print_step("[3/4]", "Analysing the prompt for issues …")
+        # ── Step 4 – Analyse the prompt ──────────────────────────────────────────
+        print_step("[4/5]", "Analysing the prompt for issues …")
 
         analysis = asyncio.run(run_with_spinner(
             analyse_prompt,
@@ -227,9 +251,7 @@ def main() -> None:
         ))
 
         print(f"\n{BOLD}── Prompt Analysis {'─' * 50}{RESET}")
-        for line in analysis.splitlines():
-            print(line)
-            sleep(0.02)  # Simulate a "typing" effect for better readability
+        print_markdown(analysis)
         print("─" * 68 + "\n")
 
         # ── Confirm before handing off to Claude Code ────────────────────────────
@@ -245,12 +267,10 @@ def main() -> None:
             continue  # Regenerate the prompt with the new context and considerations.
 
         print("\n\n")
-        print_step("[4/4]", "Passing prompt to Claude Code …")
+        print_step("[5/5]", "Passing prompt to Claude Code …")
         print_success("Prompt preview:")
         print("-" * 68)
-        for line in prompt_md.splitlines():
-            print(line)
-            sleep(0.02)  # Simulate a "typing" effect for better readability
+        print_markdown(prompt_md)
         print("-" * 68)
         answer = input("\nAre you sure? This will run the Claude Code CLI with the generated prompt. [y/N/c] ").strip().lower()
         if answer == "n":
@@ -265,11 +285,152 @@ def main() -> None:
         break
             
 
-    # ── Step 4 – Pass prompt to Claude Code ──────────────────────────────────
+    # ── Step 5 – Pass prompt to Claude Code ──────────────────────────────────
     print()
     asyncio.run(_pass_to_claude_code(prompt_md, task_id, None))
 
 
+REPL_HELP = f"""\
+{BOLD}BOB Dev interactive shell{RESET}
+  /task <ID> [--path P]   Run the fetch → prompt → Claude Code workflow for a task.
+  /agent [GROK|OPENAI]    Show or switch the LLM backend for this session.
+  /path [P]               Show or set the target project path for this session.
+  /configure              Re-run the setup wizard.
+  /reset                  Clear the chat history for this session.
+  /help                   Show this message.
+  /exit, /quit            Leave the shell.
+Anything else is sent as a chat message to the configured AI backend.
+"""
+
+
+def _run_repl(agent: str, path: str) -> None:
+    """Interactive shell: chat with the configured AI, or run task workflows on demand."""
+
+    session_agent = agent
+    session_path  = path
+    history: list[dict] = [{
+        "role": "system",
+        "content": (
+            "You are BOB, a helpful assistant embedded in a developer's terminal. "
+            "You may be asked general questions or asked to reason about a software task. "
+            "Be concise and practical."
+        ),
+    }]
+
+    print_step("[BOB]", f"Interactive mode — backend: {session_agent} ({llm_model(session_agent)})")
+    print_info("Type /help for commands, or just start chatting.")
+    print()
+
+    while True:
+        try:
+            line = input(f"{BOLD}bob-dev›{RESET} ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            break
+
+        if not line:
+            continue
+
+        if line in ("/exit", "/quit"):
+            break
+
+        if line == "/help":
+            print(REPL_HELP)
+            continue
+
+        if line == "/reset":
+            history = history[:1]
+            print_success("Chat history cleared.")
+            continue
+
+        if line == "/configure":
+            _run_configure()
+            continue
+
+        if line.startswith("/agent"):
+            parts = line.split(maxsplit=1)
+            if len(parts) == 1:
+                print_info(f"Current backend: {session_agent} ({llm_model(session_agent)})")
+                continue
+            choice = parts[1].strip().upper()
+            if choice not in ("GROK", "OPENAI"):
+                print_error("Usage: /agent [GROK|OPENAI]")
+                continue
+            if choice == "GROK" and not GROK_API_KEY:
+                print_error("GROK API key is not configured. Run /configure.")
+                continue
+            if choice == "OPENAI" and not OPENAI_API_KEY:
+                print_error("OpenAI API key is not configured. Run /configure.")
+                continue
+            session_agent = choice
+            print_success(f"Backend switched to {session_agent} ({llm_model(session_agent)}).")
+            continue
+
+        if line.startswith("/path"):
+            parts = line.split(maxsplit=1)
+            if len(parts) == 1:
+                print_info(f"Current path: {Path(session_path).resolve()}")
+                continue
+            candidate = Path(parts[1].strip()).expanduser()
+            if not candidate.exists() or not candidate.is_dir():
+                print_error(f"Invalid project path: {candidate}")
+                continue
+            session_path = str(candidate)
+            print_success(f"Path set to {Path(session_path).resolve()}.")
+            continue
+
+        if line.startswith("/task"):
+            parts = line.split(maxsplit=1)
+            if len(parts) == 1 or not parts[1].strip():
+                print_error("Usage: /task <ID> [--path P]")
+                continue
+
+            task_args = parts[1].split()
+            task_id_raw = task_args[0]
+            task_path = session_path
+            if "--path" in task_args:
+                idx = task_args.index("--path")
+                if idx + 1 < len(task_args):
+                    task_path = task_args[idx + 1]
+
+            try:
+                _run_one_shot(task_id_raw, task_path, session_agent)
+            except SystemExit as exc:
+                if exc.code not in (0, None):
+                    print_error(f"Task workflow exited with code {exc.code}.")
+            print()
+            continue
+
+        if line.startswith("/"):
+            print_error(f"Unknown command: {line}. Type /help for a list of commands.")
+            continue
+
+        # ── Freeform chat with the configured AI backend ─────────────────────
+        if session_agent == "GROK" and not GROK_API_KEY:
+            print_error("GROK API key is not configured. Run /configure.")
+            continue
+        if session_agent == "OPENAI" and not OPENAI_API_KEY:
+            print_error("OpenAI API key is not configured. Run /configure.")
+            continue
+
+        history.append({"role": "user", "content": line})
+        try:
+            reply = asyncio.run(run_with_spinner(
+                chat_completion,
+                history, session_agent, GROK_API_KEY, OPENAI_API_KEY,
+                label="Thinking",
+            ))
+        except Exception as exc:  # noqa: BLE001 - surface any backend error to the user
+            print_error(f"Chat request failed: {exc}")
+            history.pop()
+            continue
+
+        history.append({"role": "assistant", "content": reply})
+        print(f"{BOLD}bob{RESET}:")
+        print_markdown(reply)
+        print()
+
+
 # ---------------------------------------------------------------------------
 # Internal helpers
 # ---------------------------------------------------------------------------