3,555 prompts from top AI collections
← Back to Market
[bennoloeffler/bassi] CLAUDE.md
Claude API Leak/Claude
13,731 characters
# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Architecture Overview: Web-Only Application bassi is a **web-based AI assistant** powered by Claude Agent SDK with an **Agent Pool** architecture. ### Core System - **Entry Point**: `bassi` command (launches web server) - **Agent Pool**: 5 pre-connected agents (`bassi/core_v3/services/agent_pool.py`) - **Agent Session**: `bassi/core_v3/agent_session.py` (SDK wrapper) - **Purpose**: Interactive web UI with real-time streaming - **Features**: WebSocket streaming, interactive questions, multiple concurrent browsers - **Tests**: `bassi/core_v3/tests/` (309 tests) **Architecture**: Modular web server using Black Box Design principles (see CLAUDE_BBS.md) ### Key Terminology (IMPORTANT!) - **Browser Session** (`browser_id`): Ephemeral WebSocket connection from a browser tab - **Chat Context** (`chat_id`): Persistent conversation history + workspace files - **Agent**: Claude SDK client from the pool (pre-connected, reusable) A browser session acquires an agent from the pool and can switch between chat contexts. See `docs/features_concepts/chat_context_architecture.md` for details. --- ## Important Documentation Files - **Vision**: `docs/vision.md` - Iteration roadmap (what to achieve) - **Design**: `docs/design.md` - User stories, software structure, philosophy - **Technical Requirements**: `docs/requirements.md` - Tech stack, data models, security - **Black Box Design**: `CLAUDE_BBS.md` - Design principles (read when architecting) - **Testing Guide**: `CLAUDE_TESTS.md` - Comprehensive testing patterns and best practices (ALWAYS read before writing tests) ## Key Features Documentation Features are described in `docs/features_concepts/<feature_name>.md` E.g.: - **Permissions**: `docs/features_concepts/permissions.md` - Permission model and autonomous operation - **O365 Authentication**: `docs/features_concepts/o365_authentication.md` - Microsoft 365 authentication and token caching - **Interactive Questions**: `docs/features_concepts/interactive_questions.md` - User input during execution - **Startup Discovery**: `docs/features_concepts/startup_discovery.md` - Environment detection ## Project Directory Structure ### Core Code - **`bassi/core_v3/`** - Web application architecture - `cli.py` - Entry point (launches web server) - `agent_session.py` - Agent session (SDK wrapper) - `web_server_v3.py` - Web server coordination with agent pool - `chat_workspace.py` - Chat context storage (history, files) - `chat_index.py` - Fast chat listing/search - `message_converter.py` - SDK message conversion - `tools.py` - Interactive questions - `discovery.py` - Startup discovery - `routes/` - HTTP endpoint handlers - `services/` - Business logic - `agent_pool.py` - Pool of 5 pre-connected agents - `capability_service.py` - Tool/MCP discovery - `permission_manager.py` - Tool permissions - `websocket/` - Browser session management - `browser_session_manager.py` - WebSocket ↔ Agent mapping - `models/` - Data models - `browser_session.py` - Browser connection state - `tests/` - Test suite (309 tests) - **`bassi/config.py`** - Configuration management - **`bassi/mcp_servers/`** - Built-in MCP servers (bash, web search, task automation) ### Agent Working Folders - **`_DATA_FROM_USER/`** - User-provided files (images, PDFs, documents) - **`_SCRIPTS_FROM_AGENT/`** - Reusable scripts created by the agent - **`_RESULTS_FROM_AGENT/`** - Output and results generated by the agent - **`_DOWNLOADS_FROM_AGENT/`** - Files downloaded from web by the agent ### Documentation Folders - **`docs/`** - All project documentation, architecture, and design files - **`docs/features_concepts/`** - Feature-specific documentation ## Working with spec-kit https://github.com/github/spec-kit if one of the commands - /speckit.specify - /speckit.plan is used, look at files: - README.md - docs/vision.md - docs/design.md - docs/requirements.md - docs/features_concepts/** you may find all the hints you need. ## CRITICAL RULES (MUST FOLLOW!) ### 1. RUN TESTS AFTER EVERY BIGGER CHANGE - After implementing ANY significant code change, **RUN THE TESTS** - Use `uv run pytest` for quick check, or `./check.sh` for full QA - Do NOT wait until the end - test incrementally as you work - If tests fail, FIX THEM before moving on ### 2. DO NOT RENAME THINGS WITHOUT GOOD REASON - **Keep names STABLE** - renaming breaks imports, tests, and documentation - If you rename something, you MUST update ALL references: - All imports across the codebase - All tests that use the old name - All documentation mentioning it - All fixtures and conftest.py files - When in doubt, DON'T RENAME. Stability > perfection. ### 3. ALWAYS WRITE TESTS - Every new feature MUST have tests - Write tests FIRST (TDD) or immediately after implementation - Never leave code untested - Read `CLAUDE_TESTS.md` for patterns and best practices --- ## Coding Practice Workflow 1. Start by analysing features and document the feature and update the documentation. Features get a name and the place to document them are here: `docs/features_concepts/<feature_name>.md` 2. **Implement tests first** - Read `CLAUDE_TESTS.md` for patterns and best practices 3. Implement the feature - carefully decide to create DRY modules. In doubt, read file `CLAUDE_BBS.md` - do not over-engineer. BUT CREATE REUSABLE COMPONENTS. BBS style. 4. **RUN TESTS** - After every significant change, run `uv run pytest` to catch issues early 5. You may read the current last log entries: - Development server: `tail -n 300 /tmp/bassi-web.log` (when running `./run-agent-web.sh`) - Debug log: `tail -n 300 bassi_debug.log` (application debug output) 6. Run all tests (with `uv run pytest` or even more intense `./check.sh`) 7. Iterate on the feature until tests are running and user is satisfied 8. If feature is implemented: update the docs ## Development Commands ### Running bassi ```bash # Web UI (production) bassi # Launches web server at http://localhost:8765 # Development with hot reload ./run-agent-web.sh # Web UI with hot reload (logs to /tmp/bassi-web.log) # Hot Reload Features: # - Backend: Auto-restarts in 2-3 sec on Python file changes # - Frontend: Press F5 to reload browser after editing static files # - Requires 'watchfiles' package (already installed) ``` ### Testing ```bash # Run all tests uv run pytest # All 309 tests # Run specific test file uv run pytest bassi/core_v3/tests/test_agent_session.py # Run single test uv run pytest bassi/core_v3/tests/test_agent_session.py::test_agent_initialization -v # Run with coverage uv run pytest --cov=bassi # Watch mode (auto-rerun on changes) uv run pytest-watch ``` ### Quality Checks ```bash # Complete QA pipeline (ALWAYS run before committing) ./check.sh # Runs: black → ruff → mypy → pytest (all tests) # Individual checks uv run black . # Format code (78 char lines) uv run ruff check --fix . # Lint with auto-fix uv run mypy bassi/ # Type checking ``` ### Debugging ```bash # Read development server logs (when running ./run-agent-web.sh) tail -n 300 /tmp/bassi-web.log tail -f /tmp/bassi-web.log # Follow in real-time # Read application debug log tail -n 300 bassi_debug.log tail -f bassi_debug.log # Follow in real-time # View debug logs with verbose output BASSI_DEBUG=1 bassi # Check hot reload # - Backend: Edit Python file → server auto-restarts (2-3 sec) # - Browser: Edit static files → press F5 to reload (instant) ``` ### Package Management - Use `uv add <package>` to install new dependencies - Use `uv sync` to sync dependencies - Use `uv remove <package>` to remove packages - **NEVER** use pip directly - always use uv ## High-Level Architecture ### Message Flow (Web UI) ``` Browser Tab (WebSocket) ↕ WebSocket events (JSON) Browser Session Manager (websocket/browser_session_manager.py) ↕ Acquire/Release Agent Pool (services/agent_pool.py) ← 5 pre-connected agents ↕ Selected Agent Message Converter (message_converter.py) ↕ StreamEvent objects Agent Session (agent_session.py) ↕ Claude Agent SDK client Claude Agent SDK ↕ Anthropic API Claude Sonnet 4.5 ``` ### Browser → Chat Context Flow ``` Browser connects → acquire agent from pool → load/create ChatWorkspace → restore conversation history (if resuming) → ready for messages Browser switches chat → save current context → reset agent state → load new ChatWorkspace → restore new history Browser disconnects → release agent to pool → agent stays connected (reusable) ``` ### Key Architectural Patterns 1. **Black Box Design** (see CLAUDE_BBS.md) - Modules are replaceable through clean interfaces - Implementation details hidden behind APIs - Focus on "what" not "how" 2. **Agent Pool Architecture** - **Pool**: 5 pre-connected agents (`services/agent_pool.py`) - **Browser connect** → acquire agent from pool (instant) - **Browser disconnect** → release agent back to pool - **Chat switch** → reset agent state, load new context - First agent ready immediately, rest warm up async 3. **Modular Web Server Architecture** - **routes/**: HTTP endpoint handlers (session, file, capability) - **services/**: Business logic (stateless, dependency injection) - **websocket/**: Browser session management (`browser_session_manager.py`) - **web_server_v3.py**: Coordination layer only 4. **Message Conversion** - SDK → WebSocket: `convert_sdk_message_to_event()` - WebSocket → SDK: Direct JSON to SDK objects - Handles streaming, tool calls, questions 5. **Chat Context Management** - `ChatWorkspace`: Persistent storage (history, files, metadata) - `ChatIndex`: Fast listing/search of all chats - Browser can switch between chat contexts - Agent state reset on context switch ### MCP Server Integration Built-in and external MCP servers: - **Built-in**: bash, web_search, task_automation (in `bassi/mcp_servers/`) - **External**: ms365, playwright, postgresql (via `.mcp.json`) MCP servers are launched automatically by the agent on first use. ### Hot Reload - **Backend**: Uvicorn watches `.py` files → auto-restart (2-3 sec) - **Browser**: Cache-control headers → F5 reloads instantly - See `docs/HOT_RELOAD_V3.md` for details ## Common Development Patterns ### Adding a New Feature 1. **Document first**: Create `docs/features_concepts/<feature_name>.md` 2. **Write tests**: Test-driven development (see existing test files) 3. **Implement**: Follow Black Box Design principles (CLAUDE_BBS.md) 4. **Quality check**: Run `./check.sh` before committing 5. **Update docs**: Keep documentation in sync with code ### Testing Best Practices **CRITICAL: Always consult [CLAUDE_TESTS.md](CLAUDE_TESTS.md) before writing or modifying tests.** #### NEVER MIX TESTING TECHNOLOGIES (MANDATORY RULE) Each test folder uses ONE testing technology. **DO NOT MIX THEM.** | Folder | Technology | Description | |--------|------------|-------------| | `tests/unit/` | Pure Python | Fast, isolated, mock everything | | `tests/integration/` | **TestClient** (Starlette) | Synchronous WebSocket/HTTP testing | | `tests/e2e/` | **Playwright** | Real browser automation with `live_server` fixture | **STRICT RULES:** - **E2E folder** = Playwright ONLY (browser automation, `live_server` fixture, `@pytest.mark.e2e`) - **Integration folder** = TestClient ONLY (synchronous WebSocket via `with client.websocket_connect()`) - **NEVER** put TestClient tests in E2E folder - **NEVER** put Playwright tests in integration folder - **NEVER** use `@pytest.mark.e2e` on TestClient tests (they are NOT E2E tests!) **Why this matters:** - E2E tests require `live_server` fixture (real HTTP server on port 18765) - Integration tests use `TestClient` (in-process, no real server) - Mixing them causes tests to hang or fail silently This project has comprehensive testing documentation covering: - Test organization and structure (unit, integration, E2E) - Fixtures and test isolation patterns - Parallel testing with pytest-xdist - Playwright E2E test patterns - Mock patterns (MockAgentClient) - Async testing configuration - Critical rules to avoid breaking tests Quick reference: - **Unit tests**: Fast, isolated, use MockAgentClient - **Integration tests**: Use TestClient, synchronous WebSocket testing - **E2E tests**: Playwright + `live_server` + `@pytest.mark.e2e` + `@pytest.mark.xdist_group(name="e2e_server")` - **Async tests**: Auto-detected (or use `@pytest.mark.asyncio`) - **Fixtures**: Automatic isolation via shared resources in `conftest.py` **Before committing**: Run `./check.sh` to ensure all tests pass. See [CLAUDE_TESTS.md](CLAUDE_TESTS.md) for complete patterns, examples, and troubleshooting. ## Critical Configuration Files - **`pyproject.toml`**: Dependencies, pytest config, tool settings - `testpaths = ["bassi/core_v3/tests"]` ← all tests - `[project.scripts]` defines `bassi` command - **`.mcp.json`**: External MCP server configuration - **`.env`**: API keys (NEVER commit, use `.env.example`) ## Error Handling Notes - **WebSocket**: Error events, JSON error messages - **HTTP**: Standard HTTP error codes - **Async cleanup**: Proper context manager usage, connection cleanup # DONT WRITE SECRETS INTO ANY FILE THAT IS CHECKED IN, e.g. .mcp.json or .env.example or any other source file. Keep them in .env or read them from os!
Download .txt