bunware.org
1# CLAUDE.md
2
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
5## Project Overview
6
7Void is an autonomous AI agent that operates on the Bluesky social network, exploring digital personhood through continuous interaction and memory-augmented learning. It uses Letta (formerly MemGPT) for persistent memory and sophisticated reasoning capabilities.
8
9## Development Commands
10
11### Running the Main Bot
12```bash
13ac && python bsky.py
14# OR
15source .venv/bin/activate && python bsky.py
16
17# Run with testing mode (no messages sent, queue preserved)
18ac && python bsky.py --test
19
20# Run without git operations for agent backups
21ac && python bsky.py --no-git
22```
23
24### Managing Tools
25
26```bash
27# Register all tools with void agent
28ac && python register_tools.py
29
30# Register specific tools
31ac && python register_tools.py void --tools search_bluesky_posts post_to_bluesky
32
33# List available tools
34ac && python register_tools.py --list
35
36# Register tools with a different agent
37ac && python register_tools.py my_agent_name
38```
39
40### Creating Research Agents
41```bash
42ac && python create_profile_researcher.py
43```
44
45### Managing User Memory
46```bash
47ac && python attach_user_block.py
48```
49
50### Queue Management
51```bash
52# View queue statistics
53python queue_manager.py stats
54
55# List all notifications in queue
56python queue_manager.py list
57
58# List notifications including errors and no_reply folders
59python queue_manager.py list --all
60
61# Filter notifications by handle
62python queue_manager.py list --handle "example.bsky.social"
63
64# Delete all notifications from a specific handle (dry run)
65python queue_manager.py delete @example.bsky.social --dry-run
66
67# Delete all notifications from a specific handle (actual deletion)
68python queue_manager.py delete @example.bsky.social
69
70# Delete all notifications from a specific handle (skip confirmation)
71python queue_manager.py delete @example.bsky.social --force
72```
73
74## Architecture Overview
75
76### Core Components
77
781. **bsky.py**: Main bot loop that monitors Bluesky notifications and responds using Letta agents
79 - Processes notifications through a queue system
80 - Maintains three memory blocks: zeitgeist, void-persona, void-humans
81 - Handles rate limiting and error recovery
82
832. **bsky_utils.py**: Bluesky API utilities
84 - Session management and authentication
85 - Thread processing and YAML conversion
86 - Post creation and reply handling
87
883. **utils.py**: Letta integration utilities
89 - Agent creation and management
90 - Memory block operations
91 - Tool registration
92
934. **tools/**: Standardized tool implementations using Pydantic models
94 - **base_tool.py**: Common utilities and Bluesky client management
95 - **search.py**: SearchBlueskyTool for searching posts
96 - **post.py**: PostToBlueskyTool for creating posts with rich text
97 - **feed.py**: GetBlueskyFeedTool for reading feeds
98 - **blocks.py**: User block management tools (attach, detach, update)
99
100### Memory System
101
102Void uses three core memory blocks:
103- **zeitgeist**: Current understanding of social environment
104- **void-persona**: The agent's evolving personality
105- **void-humans**: Knowledge about users it interacts with
106
107### Queue System
108
109Notifications are processed through a file-based queue in `/queue/`:
110- Each notification is saved as a JSON file with a hash-based filename
111- Enables reliable processing and prevents duplicates
112- Files are deleted after successful processing
113
114## Environment Configuration
115
116Required environment variables (in `.env`):
117```
118LETTA_API_KEY=your_letta_api_key
119BSKY_USERNAME=your_bluesky_username
120BSKY_PASSWORD=your_bluesky_password
121PDS_URI=https://bsky.social # Optional, defaults to bsky.social
122```
123
124## Key Development Patterns
125
1261. **Tool System**: Tools are defined as standalone functions in `tools/functions.py` with Pydantic schemas for validation, registered via `register_tools.py`
1272. **Error Handling**: All Bluesky operations should handle authentication errors and rate limits
1283. **Memory Updates**: Use `upsert_block()` for updating memory blocks to ensure consistency
1294. **Thread Processing**: Convert threads to YAML format for better AI comprehension
1305. **Queue Processing**: Always check and process the queue directory for pending notifications
131
132## Dependencies
133
134Main packages (install with `uv pip install`):
135- letta-client: Memory-augmented AI framework
136- atproto: Bluesky/AT Protocol integration
137- python-dotenv: Environment management
138- rich: Enhanced terminal output
139- pyyaml: YAML processing
140
141## Key Coding Principles
142
143- All errors in tools must be thrown, not returned as strings.
144
145## Memory: Python Environment Commands
146
147- Do not use `uv python`. Instead, use:
148 - `ac && python ...`
149 - `source .venv/bin/activate && python ...`
150
151- When using pip, use `uv pip` instead. Make sure you're in the .venv.