Pi-Digby Documentation Home
Relevant source files
The following files were used as context for generating this wiki page:
Pi-Digby is an AI-powered Slack bot designed for the Brainwaves organization. It is built using the pi-agent-core framework and leverages Amazon Bedrock (Claude 3.5 Sonnet) as its core Large Language Model (LLM). The system is architected to run on AWS ECS Fargate with persistent storage provided by Amazon EFS, enabling per-channel memory, logging, and custom skill execution.
The bot operates primarily via Slack Socket Mode, removing the need for public HTTP endpoints. It supports complex workflows including file processing, persistent conversation memory, scheduled events, and integration with external tools via the Model Context Protocol (MCP).
Sources: CLAUDE.md:1-15, package.json:20-30
System Architecture
The Pi-Digby architecture consists of a containerized Node.js application deployed within an AWS Fargate environment. Persistence is managed through an EFS mount at /data, which stores channel-specific directories, logs, and agent memory.
Infrastructure Overview
The infrastructure is defined via CloudFormation and includes the following key components:
- Compute: AWS ECS Fargate Task running a Docker container.
- Storage: Amazon EFS for persistent data across container restarts.
- LLM Provider: Amazon Bedrock (specifically Claude Sonnet 4.6).
- Network: Private VPC with public subnets for egress; Slack communication uses Socket Mode.
Sources: CLAUDE.md:5-15, deploy/cloudformation.yml:380-450
Deployment Diagram
The following diagram illustrates the deployment structure and data flow between AWS services and the Slack interface.
The diagram shows how the core application interacts with AWS managed services and the Slack API.
Sources: CLAUDE.md:7-15, deploy/cloudformation.yml:416-435
Agent Lifecycle and Execution
The execution of a "run" is managed by ChannelRunner. Each Slack channel is assigned a dedicated queue and runner to ensure sequential processing of messages within that context.
Run Flow
- Event Reception: A Slack event (mention or DM) is received via
SlackClient. - Context Preparation: The system downloads attachments and retrieves channel-specific state.
- Runner Activation:
getOrCreateRunnerinitializes or retrieves theChannelRunner. - Prompt Building: A dynamic system prompt is generated using global memory, channel memory, and available skills.
- LLM Execution: The agent processes the input using Amazon Bedrock.
- Surface Update:
SlackSurfacemanages the live update of the Slack message (Thinking -> Progress -> Final Response).
Sources: src/main.ts:98-150, src/agent/setup.ts:168-220
Run Lifecycle Sequence
This sequence illustrates the path from a Slack notification to the final agent response.
Sources: src/main.ts:107-160, src/agent/setup.ts:250-320
Key Components and Modules
| Component | File Path | Description |
|---|---|---|
| Main Entry | src/main.ts | Bootstraps the HTTP server, Slack client, and events watcher. |
| Agent Setup | src/agent/setup.ts | Orchestrates Agent creation, session management, and tool binding. |
| System Prompt | src/agent/prompt.ts | Builds the LLM instructions, including Slack formatting and environment context. |
| Slack Surface | src/surface/slack.ts | Manages the UI lifecycle in Slack, including "thinking" states and cost footers. |
| Slack Client | src/slack/client.ts | Wraps Slack Web/Socket APIs with retry logic and backfill capabilities. |
| Event Watcher | src/events/watcher.ts | Monitors /data/events for scheduled or periodic triggers. |
Sources: CLAUDE.md:25-40, package.json:5-10
Storage and Persistence Layout
The EFS mount at /data is the source of truth for all agent state. The directory structure is organized to isolate channel data and global configuration.
Directory Structure
/data/MEMORY.md: Global memory shared across all channels./data/SYSTEM.md: Log of environment modifications (packages installed, etc.)./data/events/: JSON files defining scheduled tasks./data/skills/: Global custom CLI tools./data/<channel-id>/:MEMORY.md: Channel-specific persistence.log.jsonl: Message history (user and bot responses).context.jsonl: Full LLM conversation state.attachments/: Files shared by users in the channel.
Sources: src/agent/prompt.ts:60-85, CLAUDE.md:12-15, entrypoint.sh:5-25
Tools and Extensions
Pi-Digby uses a suite of tools to interact with the host environment and external services.
Core Tools
- bash: Runs shell commands and manages package installations.
- read/write/edit: File system operations for surgical or bulk changes.
- attach: Shares files back to the Slack channel.
- react: Adds emoji reactions to messages.
Sources: src/agent/prompt.ts:195-205, src/tools/edit.ts:110-120, src/tools/read.ts:15-30
MCP Integration
The bot utilizes the pi-mcp-adapter to load Model Context Protocol servers. Configuration is stored in .pi/mcp.json and mirrored to EFS for persistence. This allows the bot to use specialized tools like the Exa search engine or browser-use CLI.
Sources: CLAUDE.md:16-17, src/agent/setup.ts:104-130, entrypoint.sh:13-20
Configuration and Secrets
The application relies on environment variables, primarily managed via AWS Secrets Manager and passed to the ECS task.
| Variable | Source | Purpose |
|---|---|---|
MOM_SLACK_APP_TOKEN | Secrets Manager | Slack Socket Mode authentication. |
MOM_SLACK_BOT_TOKEN | Secrets Manager | Slack Web API / OAuth token. |
LINEAR_API_KEY | Secrets Manager | Optional integration for Linear issue tracking. |
AWS_REGION | ECS Task Env | Required for Bedrock and CloudWatch logs. |
Sources: CLAUDE.md:46-56, deploy/cloudformation.yml:458-475
Summary
Pi-Digby Home Documentation provides the structural foundation for the Brainwaves Slack agent. By combining pi-agent-core with AWS serverless infrastructure, the system achieves a persistent, tool-capable assistant that maintains context across sessions and channels while leveraging high-performance LLMs through Amazon Bedrock.