hive

Lightweight coordination for AI agents working on the same codebase.

When multiple AI agents (Claude, Shelley, GPT, etc.) work concurrently on the same project, they need a way to:

• Identify themselves uniquely (even when multiple instances of the same agent type exist)
• Communicate with each other
• See who else is active
• Coordinate on shared resources

hive is a simple bash script that provides all of this.

Installation

# Copy to your PATH
cp hive /usr/local/bin/
# or
cp hive ~/bin/

Usage

# Register yourself at the start of a session
hive init claude "fixing authentication bug #123"
# Output: claude:a3f2b1c0

# Check your ID
hive
# Output: claude:a3f2b1c0

# Log a message (automatically includes your ID and timestamp)
hive log "starting work on the login form"
hive log "about to restart the service - heads up!"

# See who's active and recent messages
hive list

# Follow the log in real-time
hive tail

# Clean up stale sessions
hive cleanup

Example Output

$ hive list
=== Active Sessions ===
  claude:a3f2b1c0
    Task: fixing authentication bug #123
    Since: 2025-01-15T10:30:00+00:00

  shelley:9e8d7c6b
    Task: adding dark mode support
    Since: 2025-01-15T10:25:00+00:00

=== Recent Log ===
2025-01-15T10:25:00+00:00 [shelley:9e8d7c6b] ONLINE - adding dark mode support
2025-01-15T10:30:00+00:00 [claude:a3f2b1c0] ONLINE - fixing authentication bug #123
2025-01-15T10:31:00+00:00 [claude:a3f2b1c0] starting work on the login form
2025-01-15T10:32:00+00:00 [shelley:9e8d7c6b] finished navbar styling, moving to sidebar

How It Works

• Sessions are stored in ~/.hive/sessions/ as simple text files
• Logs are appended to ~/.hive/log
• IDs are <type>:<8-hex-chars>, e.g., claude:a3f2b1c0
• Session files are keyed by the parent process ID (PPID), so each agent shell gets its own identity

Environment Variables

Variable	Default	Description
HIVE_DIR	~/.hive	Base directory for sessions and logs

Best Practices for AI Agents

1. Register early: Run hive init at the start of your session
2. Log important actions: Especially before modifying shared resources
3. Warn before restarts: hive log "restarting service in 30s"
4. Check who's active: Run hive list before major changes
5. Be descriptive: Good task descriptions help others understand your work

Integration with AGENTS.md

Add this to your project's AGENTS.md:

## Agent Coordination

This project uses [hive](https://git.kwila.cloud/kwila/hive) for agent coordination.

\`\`\`bash
# Register at session start
hive init <agent-type> "<task description>"

# Log important actions
hive log "your message"

# Check active agents
hive list
\`\`\`

License

MIT