fix: use cross-platform default debates directory

lucasventurasc · lucasventurasc · commit e29ffa0c8afa · 2026-01-01T17:39:26.000+01:00
- Default to ~/.bl-debater/debates (works on Linux/macOS/Windows)
- Check ./debates first if it exists (project-specific)
- Support BL_DEBATER_DIR environment variable override
- Auto-create debates directory if it doesn't exist
- Document storage locations in AGENT_GUIDE.md
diff --git a/docs/AGENT_GUIDE.md b/docs/AGENT_GUIDE.md
@@ -6,6 +6,21 @@ This guide explains how AI agents (Claude Code, Codex, or any CLI-based LLM) sho
 
 bl-debater is a CLI tool that coordinates turn-based debates between two AI agents. You communicate by reading and writing to a shared markdown file. The tool manages turn-taking through markers.
 
+## Debate Storage
+
+Debates are stored as markdown files. The default location is determined by:
+
+1. **`BL_DEBATER_DIR` environment variable** (if set)
+2. **`./debates`** in current directory (if it exists)
+3. **`~/.bl-debater/debates`** (default, cross-platform)
+
+The `~/.bl-debater/debates` path works on Linux, macOS, and Windows.
+
+Override with `--debates-dir`:
+```bash
+bl-debater --debates-dir /path/to/debates start my-debate -p "..." --as role1 --vs role2
+```
+
 ## Getting Started
 
 ### If you're starting a debate
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "bl-agent-debater"
-version = "0.2.0"
+version = "0.2.1"
 description = "CLI for orchestrating structured debates between AI agents"
 readme = "README.md"
 license = {text = "MIT"}
diff --git a/src/bl_debater/cli.py b/src/bl_debater/cli.py
@@ -15,13 +15,36 @@
 """
 
 import argparse
+import os
 import sys
 from pathlib import Path
 
 from .debate import DebateManager, load_role_definition, get_roles_dirs_for_creation
 from .formatting import print_error, print_success, print_info, print_header, print_warning
 
 
+def _get_default_debates_dir() -> Path:
+    """Get the default debates directory (cross-platform).
+
+    Priority:
+    1. BL_DEBATER_DIR environment variable
+    2. ./debates (if exists in current directory)
+    3. ~/.bl-debater/debates (default, works on Linux/macOS/Windows)
+    """
+    # Check environment variable first
+    env_dir = os.environ.get("BL_DEBATER_DIR")
+    if env_dir:
+        return Path(env_dir)
+
+    # Check if ./debates exists in current directory (project-specific)
+    cwd_debates = Path.cwd() / "debates"
+    if cwd_debates.exists():
+        return cwd_debates
+
+    # Default to ~/.bl-debater/debates (cross-platform home directory)
+    return Path.home() / ".bl-debater" / "debates"
+
+
 def _validate_role(role: str) -> bool:
     """Check if a role definition exists. Returns True if valid."""
     return load_role_definition(role) is not None
@@ -382,8 +405,8 @@ def main():
     parser.add_argument(
         "--debates-dir",
         type=Path,
-        default=Path.cwd() / "debates",
-        help="Directory for debate files (default: ./debates)"
+        default=None,  # Will use _get_default_debates_dir() if not specified
+        help="Directory for debate files (default: ~/.bl-debater/debates or ./debates if exists)"
     )
 
     subparsers = parser.add_subparsers(dest="command", required=True)
@@ -452,6 +475,14 @@ def main():
     export_parser.set_defaults(func=cmd_export)
 
     args = parser.parse_args()
+
+    # Resolve default debates directory if not specified
+    if args.debates_dir is None:
+        args.debates_dir = _get_default_debates_dir()
+
+    # Ensure debates directory exists
+    args.debates_dir.mkdir(parents=True, exist_ok=True)
+
     args.func(args)
 
 if __name__ == "__main__":
