Getting Started

Relevant source files

The following files were used as context for generating this wiki page:

• package.json
• CLAUDE.md
• AGENTS.md
• src/main.ts
• src/agent/setup.ts
• deploy/cloudformation.yml
• entrypoint.sh

pi-digby is a Slack bot assistant powered by Amazon Bedrock (Claude Sonnet 3.5/3.6) and built on the pi-agent-core framework. It is designed to run within AWS ECS Fargate, utilizing EFS for persistent storage of logs, memory, and custom skills. The bot operates in Socket Mode, removing the need for public endpoints while providing a robust environment for executing bash commands, managing files, and delegating complex coding tasks through integrated tools like Claude Code.

Sources: CLAUDE.md:1-15, src/agent/setup.ts:46-46

Environment Requirements

To run pi-digby, the following software and environment configurations are required:

• Node.js: Version 20.0.0 or higher.
• Package Manager: npm for dependency management.
• AWS Infrastructure: Amazon Bedrock access (specifically Claude Sonnet models) and ECS/EFS for deployment.
• Slack Credentials: App-level and Bot tokens for Socket Mode communication.

Sources: package.json:44-46, CLAUDE.md:41-48, src/main.ts:36-39

Required Environment Variables

The following secrets must be configured (typically via AWS Secrets Manager) for the application to function:

Variable	Purpose
MOM_SLACK_APP_TOKEN	Slack App-level token for Socket Mode.
MOM_SLACK_BOT_TOKEN	Slack Bot User OAuth token.
LINEAR_API_KEY	(Optional) API key for Linear agent integration.
LINEAR_WEBHOOK_SECRET	(Optional) Secret for validating Linear webhooks.
BROWSER_USE_API_KEY	API key for the browser-use cloud browser CLI.

Sources: CLAUDE.md:41-48, src/main.ts:33-34, deploy/cloudformation.yml:510-530

Local Development Setup

The project uses a specific set of commands to ensure code quality and build stability.

1. Install Dependencies: Run npm install.
2. Linting & Typechecking: Use npm run check to run Biome linting and tsgo typechecking. This must pass before committing.
3. Building: Run npm run build to compile TypeScript to the dist/ directory.

Development Commands Summary

Command	Description
npm run check	Runs Biome formatting/linting and tsgo typecheck.
npm run build	Compiles the project using tsgo.
npm test	Executes unit tests using vitest.
npx tsgo --noEmit	Quick typecheck without linting.

Sources: package.json:11-15, AGENTS.md:11-15, CLAUDE.md:21-25

Architecture Overview

The system architecture follows a containerized approach deployed on AWS. The application logic is separated from persistent data via Amazon EFS.

This diagram illustrates the high-level relationship between the ECS Fargate tasks, persistent EFS storage, and external API providers.

Sources: CLAUDE.md:5-15, deploy/cloudformation.yml:450-500, entrypoint.sh:1-25

Initializing the Agent

When the application starts, it executes entrypoint.sh followed by src/main.ts. The startup sequence involves setting up persistent symlinks and initializing the Slack client.

Startup Sequence

1. Storage Setup: entrypoint.sh creates symlinks from /data/.pi and /data/.gitconfig to the root directory to ensure settings and tokens persist across container restarts.
2. MCP Configuration: Seeds the Model Context Protocol (MCP) configuration from the repo defaults if it does not exist on EFS.
3. Client Initialization: The SlackClient starts, authenticates via auth.test, and fetches all available users and channels.
4. Backfill: The bot scans channel history to log messages missed while the bot was offline.

The sequence above details the initialization steps required to bring the bot online and sync state.

Sources: entrypoint.sh:5-20, src/main.ts:160-175, src/slack/client.ts:60-75

Core Components

The following modules represent the primary logic of the system:

1. The Runner (ChannelRunner)

Created via src/agent/setup.ts, the ChannelRunner orchestrates the lifecycle of a single message run. It handles tool binding, system prompt construction, and execution of the AgentSession.

2. The Slack Surface

Located in src/surface/slack.ts, this component manages the UI in Slack. It handles "thinking" placeholders, progress updates, tool labels, and final responses. It ensures all Slack updates are serialized to prevent race conditions.

3. Event Watcher

The system monitors ${workingDir}/events/ for JSON files defining immediate, one-shot, or periodic (cron) tasks. This allows the bot to "wake up" and perform background activities.

Sources: src/agent/setup.ts:98-115, src/surface/slack.ts:38-55, src/main.ts:182-195

Deployment

Deployment is automated via GitHub Actions. Pushing to the main branch triggers a workflow that:

1. Builds the Docker image.
2. Pushes the image to Amazon ECR.
3. Updates the ECS service.

The infrastructure is managed via the CloudFormation template found in deploy/cloudformation.yml, which defines the VPC, ECS cluster, EFS file system, and IAM roles.

Sources: CLAUDE.md:33-36, deploy/cloudformation.yml:1-10

Summary

To get started with pi-digby, a developer must ensure they have a Node.js 20 environment, configure the necessary Slack and AWS credentials, and understand the relationship between the ephemeral container and persistent EFS storage. The system is designed for reliability with automatic retries for Slack API calls and persistent memory across restarts.