[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!