Skip to main content

Penguin Documentation

Penguin is an open-source coding agent built on a scalable cognitive architecture runtime.

It is designed for long-running, tool-using, multi-agent software workflows: from interactive coding in the TUI to persistent sessions, subagent delegation, and API-driven automation. Penguin combines a coding-focused agent runtime with durable state, workspace-aware tools, and multiple interfaces on top of the same core.

Features​

  • Advanced Conversation Management: Checkpoint and snapshot system with branching and rollback
  • Multi-Agent Architecture: Per-agent conversations, model configs, tool defaults, and state isolation
  • Real-time Streaming: Enhanced streaming with event-driven architecture, reasoning support, and UI coordination
  • Token Management: Context window management with category-based budgets and image handling
  • Runtime Model Switching: Dynamic model switching with automatic configuration updates
  • Fast Startup: Deferred initialization for improved performance (fast_startup mode)
  • Comprehensive Diagnostics: Performance monitoring, telemetry tracking, and startup reporting
  • Event-Driven Architecture: Real-time UI updates via unified EventBus system
  • GitHub Integration: Webhook support for automated workflows and CI/CD pipelines
  • Memory System: Pluggable memory providers with vector search and semantic retrieval
  • Security & Permissions: Comprehensive permission engine with configurable modes, approval flows, and audit logging
  • Message Routing: MessageBus protocol for agent-to-agent and human-to-agent communication
  • Agent Management: Pause/resume controls, delegation patterns, and persona configurations
  • File manipulation and code generation
  • Web searches for up-to-date information
  • Automated task execution with Engine and Run Mode
  • Project management with SQLite persistence
  • Blueprint-driven development with spec parsing and DAG-based task scheduling
  • ITUV Workflow Orchestration (Implement, Test, Use, Verify) with native and Temporal backends
  • Custom tool integration with lazy loading
  • PyDoll browser automation
  • REST API and WebSocket streaming
  • Diagnostic logging and error handling

Quick Start​

Installation Options​

Penguin requires Python 3.10 through 3.12.

Recommended Installation (default runtime):

uv tool install penguin-ai

# Alternative
pip install penguin-ai

Compatibility aliases / optional extras:

pip install "penguin-ai[web]"         # compatibility alias; base install already includes web runtime
pip install "penguin-ai[tui]"         # compatibility alias; base install already includes TUI runtime
pip install "penguin-ai[legacy_tui]"  # old Textual prototype / experimental UI
pip install "penguin-ai[minimal]"     # library-only footprint

Basic Usage​

Terminal Interfaces:

# Default terminal UI
penguin

# Explicit TUI aliases
ptui
penguin-tui

# Headless/scriptable CLI
penguin-cli -p "Write a hello world script"

# Project management via CLI
penguin-cli project create "My Project"
penguin-cli project task create <PROJECT_ID> "Implement authentication"

Tip: Inside the interactive chat, type /help to see in-chat commands for models, streaming, checkpoints, context files, and Run Mode. See also: Usage → CLI Commands.

Web Interface:

# Start web server (already included in the base install)
penguin-web

Python API:

from penguin import PenguinAgent

agent = PenguinAgent()
response = agent.chat("Help me debug this function")

Documentation Structure​

Getting Started​

System Architecture​

Usage Guides​

Advanced Topics​

API Reference​

Architecture Overview​

Penguin uses a modular runtime architecture with event-driven communication, durable state, and explicit ownership boundaries. PenguinCore wires collaborators and preserves compatibility methods; runtime behavior lives in focused modules such as penguin.core_runtime, penguin.engine, penguin.run_mode, penguin.web.services, and the relevant domain packages. Live UI/SSE/TUI events are normalized through Penguin's RuntimeEvent envelope before being projected into client-specific payloads.

Multi-Agent and Sub-Agent Workflows​

Penguin's orchestration layer now speaks to both primary agents and scoped sub-agents so complex requests can fan out to specialized workers while preserving a shared context. See Multi-Agent Orchestration and Sub-Agent Delegation for deep dives.

  • Multi-Agent Conversations: Every REST and WebSocket surface accepts an optional agent_id so callers can direct traffic to a specific persona or service partition. The coordinator keeps a per-agent conversation state while still exposing a unified system log and analytics feed.
  • Sub-Agent Delegation: The Engine/conversation pipeline can spawn delegated subtasks that inherit the parent's tools, memory, and checkpoints. Sub-agents can be restricted to read-only or analysis-only modes and publish partial results back to the parent stream for review.
  • State Isolation with Shared Memory: All agents share the same global memory store for recall, but runtime variables (current objective, active tools, run mode) are isolated per agent so experiments remain deterministic.
  • Client Support: The Python client, REST API, and websocket streaming helpers all accept agent_id, enabling automation scripts or UI layers to switch personas mid-conversation without reinitializing the core.
  • Roadmap: Upcoming iterations will add policy-based routing, automatic sub-agent scaling, and richer capability introspection so orchestration decisions can be data-driven.

Core Components​

  • penguin.core - PenguinCore construction, delegation, and compatibility methods
  • penguin.core_runtime - Extracted runtime helpers for processing, model/provider behavior, checkpoints, token usage, action mapping, OpenCode/TUI bridging, diagnostics, and compatibility shims
  • penguin.engine - High-level reasoning loop with multi-step task execution and stop conditions
  • penguin.system - Advanced conversation management with per-agent sessions, checkpoints, runtime event envelopes, and durable event replay
  • penguin.llm - Enhanced API client with streaming, reasoning models, and provider abstraction
  • penguin.cli - Command-line interface with TUI, EventBus integration, and performance monitoring
  • penguin.web - FastAPI server with REST API, WebSocket streaming, and GitHub webhooks
  • penguin.multi - Multi-agent coordinator with role-based routing and delegation
  • penguin.project - SQLite-backed project and task management with Blueprint parsing and DAG scheduling
  • penguin.orchestration - ITUV workflow orchestration with native and Temporal backends
  • penguin.tools - Extensible tool ecosystem with lazy loading and fast startup
  • penguin.memory - Pluggable memory providers with vector search and persistence
  • penguin.security - Permission engine with policies, approval flows, and audit logging
  • penguin.telemetry - Performance tracking, token usage, and diagnostics collection

Key Architecture Improvements​

  • Event-Driven Communication: Unified EventBus for real-time UI updates and system coordination
  • Multi-Agent Support: Per-agent conversations, API clients, model configs, and tool defaults
  • Checkpoint System: Advanced conversation state management with branching and rollback
  • Enhanced Streaming: Real-time response streaming with reasoning support and callback compatibility
  • Token Management: Category-based budgeting with image optimization and per-agent tracking
  • Fast Startup: Deferred memory indexing and lazy tool initialization (~2-3x faster)
  • Provider Abstraction: Multiple client handlers (native, LiteLLM, OpenRouter) with auto-fallback
  • Configuration Management: Enhanced config resolution with live updates and persona support
  • MessageBus Protocol: Structured agent-to-agent and human-to-agent communication
  • GitHub Integration: Webhook handlers for CI/CD, issue tracking, and automated workflows
  • Telemetry System: Comprehensive performance tracking, token usage, and diagnostics
  • Engine Layer: High-level task orchestration with stop conditions and iteration control

Contributing​

Contributions are welcome! Please see our contributing guidelines for details.

License​

This project is licensed under the GNU Affero General Public License v3.0. See the LICENSE file for details.