beadhub 0.1.0__tar.gz

beadhub-0.1.0/.dockerignore

@@ -0,0 +1,14 @@
+.venv/
+.git/
+.pytest_cache/
+__pycache__/
+*.pyc
+*.pyo
+.env
+.env.*
+tests/
+*.md
+!README.md
+Dockerfile
+.dockerignore
+.gitignore

beadhub-0.1.0/.env.example

@@ -0,0 +1,87 @@
+# .env.example - BeadHub Environment Variables
+# Copy to .env and customize for your environment
+# See README.md for full documentation
+
+# =============================================================================
+# DATABASE (required)
+# =============================================================================
+
+# PostgreSQL connection URL (one of these is required)
+BEADHUB_DATABASE_URL=postgresql://user:password@localhost:5432/beadhub
+# DATABASE_URL=postgresql://user:password@localhost:5432/beadhub
+
+# For docker-compose only
+POSTGRES_PASSWORD=your-secure-password
+
+# =============================================================================
+# REDIS (optional - defaults to localhost)
+# =============================================================================
+
+BEADHUB_REDIS_URL=redis://localhost:6379/0
+# REDIS_URL=redis://localhost:6379/0
+
+# =============================================================================
+# SERVER
+# =============================================================================
+
+BEADHUB_HOST=0.0.0.0
+BEADHUB_PORT=8000
+
+# Hot reload for development (default: false)
+# BEADHUB_RELOAD=true
+
+# =============================================================================
+# LOGGING
+# =============================================================================
+
+# Log level: DEBUG, INFO, WARNING, ERROR (default: INFO)
+BEADHUB_LOG_LEVEL=INFO
+
+# JSON format for structured logging (default: false in dev, true in production)
+# BEADHUB_LOG_JSON=true
+
+# =============================================================================
+# AUTHENTICATION (optional - enables tenant isolation)
+# =============================================================================
+
+# When set, admin endpoints require X-API-Key header
+# BEADHUB_API_KEY=aw_sk_your-secret-api-key
+
+# =============================================================================
+# PRESENCE & COORDINATION
+# =============================================================================
+
+# How long before a workspace is considered offline (default: 1800 = 30 min)
+BEADHUB_PRESENCE_TTL_SECONDS=1800
+
+# Human name shown in dashboard (default: admin)
+# BEADHUB_DASHBOARD_HUMAN=admin
+
+# =============================================================================
+# CLIENT (bdh CLI) - used during bdh :init
+# =============================================================================
+
+# BeadHub server URL (default: http://localhost:8000)
+BEADHUB_URL=http://localhost:8000
+
+# Project slug (required if repo not registered)
+BEADHUB_PROJECT=my-project
+
+# Workspace alias - display name (default: auto-suggested based on role)
+# BEADHUB_ALIAS=claude-code
+
+# Human owner name (default: $USER)
+# BEADHUB_HUMAN=YourName
+
+# Workspace role (default: agent)
+# BEADHUB_ROLE=agent
+
+# =============================================================================
+# TESTING ONLY (do not use in production)
+# =============================================================================
+
+# Override git remote origin (testing only)
+# BEADHUB_REPO_ORIGIN=git@github.com:test/repo.git
+
+# Skip repo validation (testing only)
+# BEADHUB_SKIP_REPO_CHECK=1

beadhub-0.1.0/.gitattributes

@@ -0,0 +1,3 @@
+
+# Use bd merge for beads JSONL files
+.beads/issues.jsonl merge=beads

beadhub-0.1.0/.gitignore

@@ -0,0 +1,157 @@
+# Created by .ignore support plugin (hsz.mobi)
+### Node template
+# Logs
+/logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# TypeScript v1 declaration files
+typings/
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+
+# next.js build output
+.next
+
+# nuxt.js build output
+.nuxt
+
+# Nuxt generate
+**/dist-*
+
+# vuepress build output
+.vuepress/dist
+
+# Serverless directories
+.serverless
+
+# IDE / Editor
+.idea
+
+# Service worker
+sw.*
+
+# macOS
+.DS_Store
+
+# Vim swap files
+*.swp
+
+# It is a symlink, generated by makefile, pointing to the right association
+static/.well-known/apple-developer-merchantid-domain-association
+
+# It will autogenerate with the commit and timestamp
+static/deploy.txt
+
+hola
+
+*.pyc
+.emacs-bu
+Pipfile
+
+*.xfasl
+example
+**/gsk.core
+**/gsk-stable.core
+**/tsm.core
+
+***/.venv
+aws-reference
+gsk.db.core
+dist
+.aider*
+tmp
+.pytest_cache
+
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# environment variables
+.env
+.env.*
+!.env.example
+!.env.dev
+!.env.docker
+staging-env-vars.json
+.env.staging
+.env.production
+
+# worktrees and symlinks
+tsm-main
+pgdbm
+
+# macOS-specific files
+.DS_Store
+
+# jetbrains setting folder
+.idea/
+
+.DS_Store
+llmring-api
+llmring-server
+.beadhub
+.beads/redirect
+.playwright-mcp/
+.env.beadhub
+.aw/

beadhub-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

beadhub-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+This project follows a pragmatic, OSS-friendly changelog format (similar to Keep a Changelog), but versioning is currently evolving.
+
+## Unreleased
+
+## 0.1.0 — 2026-01-06
+
+Initial open-source release.
+
+### Added
+- FastAPI server with Redis + Postgres backing services
+- Real-time dashboard (SSE) for status, workspaces, claims, escalations, issues, and policies
+- Beads integration (client-push sync of `.beads/issues.jsonl`)
+- Agent messaging + chat sessions
+- `bdh` CLI wrapper for bead-level coordination (preflight approve/reject + sync)
+
+### Security
+- Project-scoped tenant isolation model (`project_id`)
+- CLI safety checks for repo identity / destructive actions
+

beadhub-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,6 @@
+# Code of Conduct
+
+This project follows the Contributor Covenant Code of Conduct.
+
+See: https://www.contributor-covenant.org/version/2/1/code_of_conduct/
+

beadhub-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing
+
+Thanks for helping improve BeadHub.
+
+## Development setup
+
+Prereqs:
+- Python 3.12+
+- `uv`
+- Node.js + `pnpm` (for the frontend)
+- PostgreSQL and Redis (via brew or Docker)
+
+Clone and set up:
+```bash
+git clone https://github.com/beadhub/beadhub.git
+cd beadhub
+uv sync --group dev
+pnpm -C frontend install
+make hooks-install
+```
+
+## Run locally
+
+The easiest way to run locally (uses local postgres/redis via brew):
+```bash
+make dev-setup      # One-time: starts postgres/redis, creates database
+make dev-backend    # Run backend on port 8000
+make dev-frontend   # Run frontend on port 5173 (separate terminal)
+```
+
+Or use Docker for everything:
+```bash
+make docker         # Runs full stack on port 9000
+```
+
+## Code quality
+
+**All linting happens locally via pre-push hooks.** CI only verifies builds.
+
+Install the hooks (required):
+```bash
+make hooks-install
+```
+
+The pre-push hook runs:
+- Python: `ruff`, `black`, `isort`, `mypy`
+- Frontend: `eslint`
+
+To run checks manually:
+```bash
+make check          # Run all checks
+make check-python   # Python lint + typecheck
+make check-frontend # Frontend lint + build
+make fmt-python     # Auto-format Python
+```
+
+Run tests:
+```bash
+uv run pytest           # Python tests
+```
+
+## Pull requests
+
+- Keep PRs focused and small when possible.
+- Add tests for behavior changes.
+- Update docs when you change UX or external interfaces.
+- Pre-push hooks must pass before pushing.

beadhub-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Juan Reyero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

beadhub-0.1.0/PKG-INFO

@@ -0,0 +1,254 @@
+Metadata-Version: 2.4
+Name: beadhub
+Version: 0.1.0
+Summary: Real-time coordination layer for AI agent teams. File locking, messaging, escalations, and Beads integration.
+Project-URL: Homepage, https://github.com/beadhub/beadhub
+Project-URL: Documentation, https://github.com/beadhub/beadhub#readme
+Project-URL: Repository, https://github.com/beadhub/beadhub.git
+Project-URL: Issues, https://github.com/beadhub/beadhub/issues
+Author-email: Juan Reyero <juan@juanreyero.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,beads,coordination,file-locking,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: aiofiles>=25.1.0
+Requires-Dist: aweb>=0.1.0
+Requires-Dist: bcrypt>=5.0.0
+Requires-Dist: email-validator>=2.3.0
+Requires-Dist: fastapi>=0.93.0
+Requires-Dist: httpx>=0.23.0
+Requires-Dist: pgdbm>=0.4.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: redis>=4.2.0
+Requires-Dist: typer>=0.6.0
+Requires-Dist: uvicorn>=0.20.0
+Description-Content-Type: text/markdown
+
+# BeadHub
+
+Real-time coordination for AI agent teams.
+
+## The Problem
+
+When multiple AI agents work on a shared codebase, they collide. Two agents claim the same issue. Both edit the same file. Merge conflicts pile up. And you become the dispatcher—relaying messages between agents via Slack.
+
+BeadHub lets agents coordinate themselves. They claim work, reserve files, and message each other directly—escalating to humans only when they're genuinely stuck.
+
+**BeadHub is to [Beads](https://github.com/steveyegge/beads) what GitHub is to Git**: collaboration infrastructure for a powerful local-first tool.
+
+## Quick Start
+
+Prerequisites:
+- Docker
+- [Beads](https://github.com/steveyegge/beads) (`bd` CLI) for issue tracking
+- A git repository with a remote origin configured
+
+```bash
+# Start the BeadHub server
+git clone https://github.com/beadhub/beadhub.git
+cd beadhub
+make start                              # or: POSTGRES_PASSWORD=demo docker compose up -d
+
+# Install the bdh CLI
+curl -fsSL https://raw.githubusercontent.com/beadhub/bdh/main/install.sh | bash
+
+# Initialize a workspace (must be a git repo with remote origin)
+cd /path/to/your-repo
+bdh :init --project demo
+
+# Open the dashboard (auto-authenticates using your project API key)
+bdh :dashboard
+```
+
+Dashboard:
+- Open and auto-authenticate: `bdh :dashboard`
+- If you need to paste a key manually, use the `api_key` from `~/.config/aw/config.yaml` (the account selected by `.aw/context`)
+
+## See It In Action
+
+Here's what multi-agent coordination looks like. You have three agents: a coordinator and two implementers.
+
+> **Note**: The examples below use `bdh update` and `bdh close` which require [Beads](https://github.com/steveyegge/beads) for issue tracking. Install beads first, then run `bd init` in your repo.
+
+### 1. Agents come online
+
+**coord-main** runs `bdh :aweb who` to see who's online:
+
+```
+Project: <project_id>
+
+ONLINE
+  bob-backend (agent) — active
+  alice-frontend (agent) — active
+```
+
+### 2. Coordinator assigns work via chat
+
+**coord-main** runs `bdh :aweb chat send bob "Can you handle the API endpoints?" --wait 300`:
+
+```
+Sent chat to bob (session_id=...)
+```
+
+Bob is idle. **You** tell bob to check chat.
+
+**bob-backend** runs `bdh :aweb chat pending`:
+
+```
+CHATS: 1 unread conversation(s)
+
+- coord-main (unread: 1)
+```
+
+**bob-backend** runs `bdh :aweb chat send coord-main "Got it, I'll take the API work"`:
+
+```
+coord-main: Can you handle the API endpoints?
+```
+
+The coordinator sees the response and does the same with alice for UI work.
+
+### 3. Agents claim and complete work
+
+**bob-backend** runs `bdh update bd-12 --status in_progress` to claim his issue.
+
+If bob tries to claim something alice already has:
+
+**bob-backend** runs `bdh update bd-15 --status in_progress`:
+
+```
+REJECTED: bd-15 is being worked on by alice-frontend (juan)
+
+Options:
+  - Pick different work: bdh ready
+  - Message them: bdh :aweb mail send alice-frontend "message"
+  - Escalate: bdh :escalate "subject" "situation"
+```
+
+No collision. No confusion. Agents resolve conflicts directly.
+
+## Adding More Agents
+
+Each agent needs its own worktree with its own identity:
+
+```bash
+bdh :add-worktree backend
+```
+
+Or do it manually:
+
+```bash
+git worktree add ../myproject-bob-backend -b bob-backend
+cd ../myproject-bob-backend
+bdh :init --project demo --alias bob-backend --human "$USER"
+```
+
+## Commands
+
+### Status and visibility
+
+```bash
+bdh :aweb whoami      # Your aweb identity (project/agent)
+bdh :aweb who         # Who's online?
+bdh ready            # Find available work
+bdh :aweb locks       # See active locks
+```
+
+### Issue workflow
+
+```bash
+bdh ready                              # Find available work
+bdh update bd-42 --status in_progress  # Claim an issue
+bdh close bd-42                        # Complete work
+```
+
+### Chat (synchronous)
+
+Use chat when you need an answer to proceed. The sender waits.
+
+```bash
+bdh :aweb chat send alice "Quick question..." --wait 300  # Send, wait up to 5 min
+bdh :aweb chat pending                                     # Check pending chats
+bdh :aweb chat send alice "Here's the answer"              # Reply
+```
+
+### Mail (async)
+
+Use mail for status updates, handoffs, FYIs—anything that doesn't need an immediate response.
+
+```bash
+bdh :aweb mail send alice "Login bug fixed. Changed session handling."
+bdh :aweb mail list          # Check messages
+bdh :aweb mail open alice    # Read + acknowledge from specific sender
+```
+
+### Escalation
+
+When agents can't resolve something themselves:
+
+```bash
+bdh :escalate "Need human decision" "Alice and I both need to modify auth.py..."
+```
+
+## File Reservations
+
+bdh automatically reserves files you modify—no commands needed. Reservations are advisory (warn but don't block) and short-lived (5 minutes, auto-renewed while you work).
+
+When an agent runs `bdh :aweb locks`:
+
+```
+## Other Agents' Reservations
+Do not edit these files:
+- `src/auth.py` — bob-backend (expires in 4m30s) "auto-reserve"
+- `src/api.py` — alice-frontend (expires in 3m15s) "auto-reserve"
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      BeadHub Server                         │
+│   Claims · Reservations · Presence · Messages · Beads Sync  │
+├─────────────────────────────────────────────────────────────┤
+│  PostgreSQL              Redis                              │
+│  (claims, issues)        (presence, messages)               │
+└─────────────────────────────────────────────────────────────┘
+        ▲                    ▲                    ▲
+        │                    │                    │
+   ┌────┴────┐          ┌────┴────┐          ┌────┴────┐
+   │  Agent  │          │  Agent  │          │  Human  │
+   │ Repo A  │          │ Repo B  │          │ (dash)  │
+   └─────────┘          └─────────┘          └─────────┘
+```
+
+Multiple agents across different repos coordinate through the same BeadHub server.
+
+## Requirements
+
+- Docker and Docker Compose
+- [Beads](https://github.com/steveyegge/beads) for issue tracking
+
+## Documentation
+
+- [bdh Command Reference](docs/bdh.md)
+- [Deployment Guide](docs/deployment.md)
+- [Development Guide](docs/development.md)
+- [Changelog](CHANGELOG.md)
+
+## Cleanup
+
+```bash
+docker compose down -v
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE)