BeeLoop

BeeLoop runs directory-backed agents with memory that receive events and message one another.

Setup

pip install -e .

Codex Setup

codex plugin marketplace add git@github.com:realAsma/BeeLoop-State.git
codex plugin add beeloop-state@beeloop-state
codex plugin marketplace add .
codex plugin add beeloop-tools@beeloop-tools

Claude Setup

claude plugin marketplace add git@github.com:realAsma/BeeLoop-State.git
claude plugin install beeloop-state@beeloop-state
claude plugin marketplace add ./
claude plugin install beeloop-tools@beeloop-tools

Root for BeeLoop and Memory Files (Optional)

By default, this checkout is the BeeLoop root and includes the orchestrator workspace. To use a different prepared BeeLoop root containing configs/ and orchestrator/, create ~/.config/beeloop/loop.toml before starting BeeLoop:

mkdir -p "$HOME/.config/beeloop"
cat > "$HOME/.config/beeloop/loop.toml" <<EOF
root = "$HOME/my-beeloop"
EOF

BeeLoop State stores memory files in ~/.beeloop_states by default. See the BeeLoop State configuration to change this location.

Getting Started

Launch the BeeLoop gateway in a detached tmux session:

tmux new-session -d -s beeloop beeloop

This runs the gateway in the background, where it waits for inputs.

Orchestrator

The orchestrator lives in the orchestrator/ workspace. It is a special, stateful, event-driven agent designed to be your chief of staff. It delegates work, shares progress, and asks when it needs input.

For design details, see the orchestrator instructions and skills.

Grow the orchestrator by talking to it and adding skills for workflows you repeat. To talk to it from the Codex or Claude Code CLI:

cd orchestrator && codex
# or
cd orchestrator && claude

To customize its personality:

cp orchestrator/SOUL_template.md orchestrator/SOUL.md

Connect a Slack App

For the best experience, use Slack as the main communication channel with the orchestrator. Follow the private Slack input setup.

Then record it as the primary communication channel:

echo 'The primary communication channel with the user is the configured Slack app in runtime/sources/slack-private.' >> orchestrator/MEMORY.md

Example Skill: Feature to Pull Request

Ask in Slack for a feature. The orchestrator delegates the work, opens a draft pull request, notifies you in Slack, and addresses your GitHub review comments until it is ready.

Work with your orchestrator to set up this flow. GitHub setup varies by organization, so talk to your orchestrator first. :)