/odra28/pi-mono

Wiki directory

Browse AI-generated documentation for any repository.

Getting Started

Relevant source files

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

The pi-mono repository is a monorepo containing a suite of tools for building AI agents and managing LLM (Large Language Model) deployments. The project provides a unified, multi-provider API for interacting with LLMs, a core agent runtime for managing state and tool calls, and several user-facing applications, including an interactive coding agent for the terminal and a self-managing Slack bot.

This guide provides an overview of the project structure, initial setup, and instructions for using the primary applications. It is intended for both users of the tools and developers looking to contribute to the project.

Sources: README.md:3-4

Project Setup

To get started with the pi-mono repository for development, you need to install dependencies and build all the packages. The project uses npm workspaces to manage the multiple packages within the monorepo.

The following diagram illustrates the basic setup workflow.

Generating architecture diagram...

This diagram shows the sequence of commands for setting up the development environment.

Sources: README.md:18-22, package.json:10-12

Install Dependencies: Install all dependencies for all packages in the workspace.
```
npm install
```
Build Packages: Build all packages. The monorepo is configured to build the packages in the correct dependency order.
```
npm run build
```
Run Checks: To ensure code quality, run the linter, formatter, and type-checker across all workspaces.
```
npm run check
```
Development Mode: For active development, you can run all packages in watch mode. This will automatically rebuild packages when changes are detected.
```
npm run dev
```

Sources: README.md:18-29, package.json:10-13

Core Packages

The monorepo is organized into several distinct packages, each with a specific purpose.

Package	Description
`@mariozechner/pi-ai`	Unified multi-provider LLM API (OpenAI, Anthropic, Google, etc.)
`@mariozechner/pi-agent-core`	Agent runtime with tool calling and state management
`@mariozechner/pi-coding-agent`	Interactive coding agent CLI
`@mariozechner/pi-mom`	Slack bot that delegates messages to the pi coding agent
`@mariozechner/pi-tui`	Terminal UI library with differential rendering
`@mariozechner/pi-web-ui`	Web components for AI chat interfaces
`@mariozechner/pi-proxy`	CORS proxy for browser-based LLM API calls
`@mariozechner/pi`	CLI for managing vLLM deployments on GPU pods

Sources: README.md:7-16

The following diagram shows the high-level dependency relationships between the main agent-related packages.

Generating architecture diagram...

This diagram illustrates how user-facing applications like pi-coding-agent and pi-mom are built upon the pi-agent-core and pi-ai libraries.

Sources: README.md:7-16, packages/coding-agent/src/main.ts:1, packages/mom/src/agent.ts:1

Using the Interactive Coding Agent (`pi-coding-agent`)

The pi-coding-agent is a powerful, interactive CLI tool that functions as an AI coding assistant with access to read/write files and execute shell commands.

Sources: packages/coding-agent/src/main.ts:258

Running the Agent

The agent is launched from the command line. You can provide an initial prompt, include files, and configure its behavior using various flags.

Common CLI Arguments

Argument	Description
`--provider <name>`	Specifies the AI provider (e.g., `openai`, `anthropic`).
`--model <id>`	Specifies the model ID to use (e.g., `gpt-4o-mini`).
`--print`, `-p`	Runs in non-interactive mode, prints the result, and exits.
`--continue`, `-c`	Continues the previous session.
`--resume`, `-r`	Opens a selector to choose a previous session to resume.
`--session <path>`	Uses a specific session file.
`--no-session`	Disables session saving for an ephemeral session.
`--tools <tools>`	A comma-separated list of tools to enable (e.g., `read,bash`).
`@<file>`	Includes the content of a file in the initial prompt.

Sources: packages/coding-agent/src/main.ts:260-300

Examples:

# Start an interactive session
pi-coding-agent

# Start with an initial prompt and include a file
pi-coding-agent @./src/main.ts "Summarize this file"

# Run a command non-interactively and print the output
pi-coding-agent -p "List all .ts files in the current directory"

Sources: packages/coding-agent/src/main.ts:302-328

Interactive TUI

The agent features a rich Terminal User Interface (TUI) for interaction.

Keybindings and Commands

Key / Command	Action
`Ctrl+P`	Cycle through available or scoped models.
`Shift+Tab`	Cycle through thinking levels (`off`, `low`, `medium`, `high`).
`Ctrl+O`	Expand or collapse the output of tool calls.
`Ctrl+T`	Toggle the visibility of the agent's "thinking" blocks.
`Esc`	Interrupt the current agent operation.
`Ctrl+C` (once)	Clear the input editor.
`Ctrl+C` (twice)	Exit the application.
`/thinking`	Open the thinking level selector.
`/model`	Open the model selector.
`/export [file]`	Export the current session to an HTML file.
`/copy`	Copy the last assistant message to the clipboard.
`/branch`	Create a new session branch from a previous message.
`/compact`	Manually trigger context compaction.
`! <command>`	Execute a bash command directly.

Sources: packages/coding-agent/src/tui/tui-renderer.ts:130-230, 477-526

Agent Tools

The agent is equipped with a set of tools to interact with the local environment.

Default Tools: read, bash, edit, write
Optional Tools: grep, find, ls

The agent can automatically download and manage required command-line utilities like fd (for file searching) and rg (ripgrep) if they are not found on the system PATH. This ensures a seamless experience without manual dependency installation.

Sources: packages/coding-agent/src/main.ts:404-411, packages/coding-agent/src/tools-manager.ts:182-199

Using the Slack Bot (`mom`)

mom (Master Of Mischief) is a self-managing Slack bot that integrates the coding agent's capabilities into a Slack workspace. It responds to mentions, executes commands in a sandboxed environment, and maintains its own persistent workspace.

Sources: packages/mom/README.md:3-6

Setup and Configuration

To run mom, you need to set up a Slack App and provide the necessary tokens as environment variables.

Environment Variables

Variable	Description
`MOM_SLACK_APP_TOKEN`	Slack app-level token (starts with `xapp-...`).
`MOM_SLACK_BOT_TOKEN`	Slack bot OAuth token (starts with `xoxb-...`).
`ANTHROPIC_API_KEY`	Your Anthropic API key.
`ANTHROPIC_OAUTH_TOKEN`	Alternative to the API key.

Sources: packages/mom/README.md:50-55

Slack App Configuration

Enable Socket Mode.
Generate an App-Level Token with connections:write scope.
Add the required Bot Token Scopes like app_mentions:read, chat:write, files:read, etc.
Subscribe to Bot Events such as app_mention and message.channels.
Install the app to your workspace to get the Bot User OAuth Token.

Sources: packages/mom/README.md:20-36

Running `mom`

The recommended way to run mom is within a Docker container to provide a secure sandbox.

# Create a persistent Docker volume for the workspace
docker run -d \
  --name mom-sandbox \
  -v $(pwd)/data:/workspace \
  alpine:latest \
  tail -f /dev/null

# Run mom, connecting to the Docker sandbox
mom --sandbox=docker:mom-sandbox ./data

Sources: packages/mom/README.md:41-48

`mom`'s Architecture

mom operates within a defined data directory, keeping all conversations, files, and custom-built tools organized and persistent.

The following diagram shows the data directory structure mom uses.

Generating architecture diagram...

This diagram shows the workspace layout for the mom bot, with global memory and skills, and per-channel directories for logs and other data.

Sources: packages/mom/README.md:121-131

When a user mentions @mom in a Slack channel, the following sequence of events occurs:

Generating architecture diagram...

This sequence diagram illustrates the flow of a request from a user in Slack to the mom application, through the AI model, and back to Slack.

Sources: packages/mom/src/agent.ts

Development and Contribution

The project follows a set of rules and a structured process for development, versioning, and publishing.

Versioning and Publishing

All packages in the monorepo use lockstep versioning, meaning they all share the same version number. Version bumps are handled via root-level npm scripts.

npm run version:patch
npm run version:minor
npm run version:major

Sources: README.md:55-61

The release process is a multi-step workflow designed to ensure consistency.

Generating architecture diagram...

This flowchart outlines the official release process for publishing new versions of the packages.

Sources: README.md:69-96, AGENTS.md:78-100

Development Rules

For contributors (human or AI), a set of development rules is defined in AGENTS.md. Key rules include:

Code Quality: Avoid any types.
Commands: Use npm run check after code changes. Never run npm run dev or npm run build in a context where it might be committed.
Commits: Never commit unless explicitly asked by a user.
Changelog: New entries must always go under the [Unreleased] section. Released version sections are immutable.

Sources: AGENTS.md:9-14, 48-52

Getting Started

Relevant source files

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

Sources: README.md:3-4

Project Setup

The following diagram illustrates the basic setup workflow.

Generating architecture diagram...

This diagram shows the sequence of commands for setting up the development environment.

Sources: README.md:18-22, package.json:10-12

Install Dependencies: Install all dependencies for all packages in the workspace.
```
npm install
```
Build Packages: Build all packages. The monorepo is configured to build the packages in the correct dependency order.
```
npm run build
```
Run Checks: To ensure code quality, run the linter, formatter, and type-checker across all workspaces.
```
npm run check
```
Development Mode: For active development, you can run all packages in watch mode. This will automatically rebuild packages when changes are detected.
```
npm run dev
```

Sources: README.md:18-29, package.json:10-13

Core Packages

The monorepo is organized into several distinct packages, each with a specific purpose.

Package	Description
`@mariozechner/pi-ai`	Unified multi-provider LLM API (OpenAI, Anthropic, Google, etc.)
`@mariozechner/pi-agent-core`	Agent runtime with tool calling and state management
`@mariozechner/pi-coding-agent`	Interactive coding agent CLI
`@mariozechner/pi-mom`	Slack bot that delegates messages to the pi coding agent
`@mariozechner/pi-tui`	Terminal UI library with differential rendering
`@mariozechner/pi-web-ui`	Web components for AI chat interfaces
`@mariozechner/pi-proxy`	CORS proxy for browser-based LLM API calls
`@mariozechner/pi`	CLI for managing vLLM deployments on GPU pods

Sources: README.md:7-16

The following diagram shows the high-level dependency relationships between the main agent-related packages.

Generating architecture diagram...

This diagram illustrates how user-facing applications like pi-coding-agent and pi-mom are built upon the pi-agent-core and pi-ai libraries.

Sources: README.md:7-16, packages/coding-agent/src/main.ts:1, packages/mom/src/agent.ts:1

Using the Interactive Coding Agent (`pi-coding-agent`)

The pi-coding-agent is a powerful, interactive CLI tool that functions as an AI coding assistant with access to read/write files and execute shell commands.

Sources: packages/coding-agent/src/main.ts:258

Running the Agent

The agent is launched from the command line. You can provide an initial prompt, include files, and configure its behavior using various flags.

Common CLI Arguments

Argument	Description
`--provider <name>`	Specifies the AI provider (e.g., `openai`, `anthropic`).
`--model <id>`	Specifies the model ID to use (e.g., `gpt-4o-mini`).
`--print`, `-p`	Runs in non-interactive mode, prints the result, and exits.
`--continue`, `-c`	Continues the previous session.
`--resume`, `-r`	Opens a selector to choose a previous session to resume.
`--session <path>`	Uses a specific session file.
`--no-session`	Disables session saving for an ephemeral session.
`--tools <tools>`	A comma-separated list of tools to enable (e.g., `read,bash`).
`@<file>`	Includes the content of a file in the initial prompt.

Sources: packages/coding-agent/src/main.ts:260-300

Examples:

# Start an interactive session
pi-coding-agent

# Start with an initial prompt and include a file
pi-coding-agent @./src/main.ts "Summarize this file"

# Run a command non-interactively and print the output
pi-coding-agent -p "List all .ts files in the current directory"

Sources: packages/coding-agent/src/main.ts:302-328

Interactive TUI

The agent features a rich Terminal User Interface (TUI) for interaction.

Keybindings and Commands

Key / Command	Action
`Ctrl+P`	Cycle through available or scoped models.
`Shift+Tab`	Cycle through thinking levels (`off`, `low`, `medium`, `high`).
`Ctrl+O`	Expand or collapse the output of tool calls.
`Ctrl+T`	Toggle the visibility of the agent's "thinking" blocks.
`Esc`	Interrupt the current agent operation.
`Ctrl+C` (once)	Clear the input editor.
`Ctrl+C` (twice)	Exit the application.
`/thinking`	Open the thinking level selector.
`/model`	Open the model selector.
`/export [file]`	Export the current session to an HTML file.
`/copy`	Copy the last assistant message to the clipboard.
`/branch`	Create a new session branch from a previous message.
`/compact`	Manually trigger context compaction.
`! <command>`	Execute a bash command directly.

Sources: packages/coding-agent/src/tui/tui-renderer.ts:130-230, 477-526

Agent Tools

The agent is equipped with a set of tools to interact with the local environment.

Default Tools: read, bash, edit, write
Optional Tools: grep, find, ls

Sources: packages/coding-agent/src/main.ts:404-411, packages/coding-agent/src/tools-manager.ts:182-199

Using the Slack Bot (`mom`)

Sources: packages/mom/README.md:3-6

Setup and Configuration

To run mom, you need to set up a Slack App and provide the necessary tokens as environment variables.

Environment Variables

Variable	Description
`MOM_SLACK_APP_TOKEN`	Slack app-level token (starts with `xapp-...`).
`MOM_SLACK_BOT_TOKEN`	Slack bot OAuth token (starts with `xoxb-...`).
`ANTHROPIC_API_KEY`	Your Anthropic API key.
`ANTHROPIC_OAUTH_TOKEN`	Alternative to the API key.

Sources: packages/mom/README.md:50-55

Slack App Configuration

Enable Socket Mode.
Generate an App-Level Token with connections:write scope.
Add the required Bot Token Scopes like app_mentions:read, chat:write, files:read, etc.
Subscribe to Bot Events such as app_mention and message.channels.
Install the app to your workspace to get the Bot User OAuth Token.

Sources: packages/mom/README.md:20-36

Running `mom`

The recommended way to run mom is within a Docker container to provide a secure sandbox.

# Create a persistent Docker volume for the workspace
docker run -d \
  --name mom-sandbox \
  -v $(pwd)/data:/workspace \
  alpine:latest \
  tail -f /dev/null

# Run mom, connecting to the Docker sandbox
mom --sandbox=docker:mom-sandbox ./data

Sources: packages/mom/README.md:41-48

`mom`'s Architecture

mom operates within a defined data directory, keeping all conversations, files, and custom-built tools organized and persistent.

The following diagram shows the data directory structure mom uses.

Generating architecture diagram...

This diagram shows the workspace layout for the mom bot, with global memory and skills, and per-channel directories for logs and other data.

Sources: packages/mom/README.md:121-131

When a user mentions @mom in a Slack channel, the following sequence of events occurs:

Generating architecture diagram...

This sequence diagram illustrates the flow of a request from a user in Slack to the mom application, through the AI model, and back to Slack.

Sources: packages/mom/src/agent.ts

Development and Contribution

The project follows a set of rules and a structured process for development, versioning, and publishing.

Versioning and Publishing

All packages in the monorepo use lockstep versioning, meaning they all share the same version number. Version bumps are handled via root-level npm scripts.

npm run version:patch
npm run version:minor
npm run version:major

Sources: README.md:55-61

The release process is a multi-step workflow designed to ensure consistency.

Generating architecture diagram...

This flowchart outlines the official release process for publishing new versions of the packages.

Sources: README.md:69-96, AGENTS.md:78-100

Development Rules

For contributors (human or AI), a set of development rules is defined in AGENTS.md. Key rules include:

Code Quality: Avoid any types.
Commands: Use npm run check after code changes. Never run npm run dev or npm run build in a context where it might be committed.
Commits: Never commit unless explicitly asked by a user.
Changelog: New entries must always go under the [Unreleased] section. Released version sections are immutable.

Sources: AGENTS.md:9-14, 48-52

Getting Started

Project Setup

Core Packages

Using the Interactive Coding Agent (pi-coding-agent)

Running the Agent

Interactive TUI

Agent Tools

Using the Slack Bot (mom)

Setup and Configuration

Running mom

mom's Architecture

Development and Contribution

Versioning and Publishing

Development Rules

Getting Started

Project Setup

Core Packages

Using the Interactive Coding Agent (pi-coding-agent)

Running the Agent

Interactive TUI

Agent Tools

Using the Slack Bot (mom)

Setup and Configuration

Running mom

mom's Architecture

Development and Contribution

Versioning and Publishing

Development Rules

Using the Interactive Coding Agent (`pi-coding-agent`)

Using the Slack Bot (`mom`)

Running `mom`

`mom`'s Architecture

Using the Interactive Coding Agent (`pi-coding-agent`)

Using the Slack Bot (`mom`)

Running `mom`

`mom`'s Architecture