Peky: The Essential TUI Every AI Developer Needs

Managing multiple AI agents simultaneously feels like conducting an orchestra where every musician plays in a separate room. You bounce between terminal windows, lose context, rebuild environments, and waste precious development time on logistics instead of creation. Peky eliminates this chaos by unifying all your AI agents—Claude Code, Codex CLI, and beyond—into a single, elegant terminal user interface that keeps your workflow organized and your productivity soaring.

This revolutionary tool transforms how developers interact with AI assistants, offering a persistent, multi-project dashboard where agents run side-by-side without window management headaches. Whether you're orchestrating complex code generation tasks, comparing agent outputs, or maintaining separate environments for different projects, Peky delivers the structure modern AI-assisted development demands.

In this deep dive, you'll discover Peky's powerful orchestration capabilities, learn how to configure project-specific layouts, explore real-world use cases, and master advanced techniques for team collaboration. We'll walk through complete installation, dissect actual configuration examples, and reveal why developers are abandoning manual terminal juggling for this sleek Go-powered solution.

What Is Peky and Why It's Transforming AI Development

Peky is a terminal user interface (TUI) built in Go that consolidates multiple AI agents into a single, manageable workspace. Created by Kevin Kern, this open-source tool addresses a critical pain point in modern development: the fragmentation that occurs when running different AI assistants across separate terminal sessions.

At its core, Peky functions as an intelligent orchestration layer. It doesn't replace your favorite AI agents—it elevates them. The tool leverages the Bubble Tea and Lipgloss frameworks from Charm.sh to deliver a buttery-smooth, visually stunning terminal experience that feels more like a modern GUI than traditional terminal multiplexers.

The architecture centers around a persistent native daemon written in Go, which maintains session state even when you close the UI. This means your Claude Code instance keeps running your long-generation tasks, your Codex CLI continues processing, and your custom agents remain active—no more lost work from accidental terminal closures. The daemon approach also enables lightning-fast UI startup times and resource-efficient operation.

Peky has gained rapid traction in the developer community because it arrives at precisely the right moment. AI-assisted coding has shifted from novelty to necessity, with developers routinely running Claude Code for complex refactoring, Codex CLI for quick commands, and specialized agents for documentation or testing. Managing these tools across tmux sessions or separate terminal windows creates cognitive overhead that Peky eliminates with its unified dashboard.

The tool's zero-configuration philosophy means you can run peky in any directory and immediately start working. Yet it scales to support sophisticated team workflows through project-local .peky.yml files that define reusable layouts, environment variables, and agent configurations. This combination of simplicity and power makes it accessible to solo developers while robust enough for engineering organizations.

Key Features That Make Peky Indispensable

🧠 AI Agent Orchestration

Peky's orchestration engine goes far beyond simple window management. The slash command system (/) provides instant access to actions like broadcasting messages to all agents simultaneously—imagine sending "explain this error" to every AI assistant at once and comparing their responses. The @ file picker integrates with your filesystem, allowing agents to access project context without manual copy-pasting. Quick-reply functionality maintains conversation flow with specific agents while keeping your dashboard organized.

🗂️ Multi-Project Dashboard

The dashboard displays all active projects and sessions in a single view, eliminating the need for ctrl+z, jobs, or window manager gymnastics. Each project gets its own session namespace, and the live preview system renders full TUI applications like vim or htop natively within panes. This is achieved through sophisticated terminal emulation that captures ANSI escape sequences and renders them correctly in the dashboard grid.

🖱️ Mouse-First Interaction

Unlike traditional terminal multiplexers that treat mouse support as an afterthought, Peky embraces it. You can create, select, resize, and drag panes with intuitive click-and-drag operations. The mouse handling integrates seamlessly with the Bubble Tea framework's event system, providing responsive feedback and eliminating the learning curve associated with complex keybindings.

🎯 True Zero Config

Peky's auto-detection mechanisms identify project types, available AI agents, and environment contexts without manual setup. When you run peky start, it scans for .peky.yml, checks for common AI agent installations, and builds a sensible default layout. This works because the Go binary includes heuristics for detecting project structures and agent configurations, making it genuinely plug-and-play.

🧭 Persistent Native Daemon

The Go daemon runs as a background service, managing all session processes. It uses Unix domain sockets for communication with the UI, enabling instant reconnection. Sessions survive UI crashes, SSH disconnections, and system sleep. The daemon implements intelligent resource management, automatically pausing idle agents and resuming them on demand.

📜 Scrollback and Copy Mode

Peky implements a native scrollback buffer with vim-style navigation. The copy mode (ctrl+k toggles RAW mode) lets you yank text directly from agent outputs without mouse selection breaking. This is crucial for capturing code snippets, error messages, or insights from AI conversations. The buffer persists across UI restarts, creating a searchable history of all agent interactions.

⌘ Command Palette

The command palette (ctrl+shift+p) provides fuzzy-searchable access to all actions. Rename sessions, switch layouts, kill panes, or trigger custom workflows without memorizing keybindings. The palette integrates with the configuration system, so team-defined commands appear automatically.

🧠 Native Live Previews

Full TUI support means running vim, htop, or any curses-based application inside Peky panes works flawlessly. The rendering engine captures 256-color palettes, true-color support, and Unicode characters correctly. This enables powerful workflows like editing code in vim while watching Codex CLI generate tests in an adjacent pane.

📁 Project-Local Configuration

The .peky.yml configuration system uses a well-defined schema that supports variable expansion, environment inheritance, and layout templating. Committing this file to git ensures every team member gets identical agent setups, window layouts, and environment variables. The configuration loader merges project-local settings with global defaults in ~/.config/peky/config.yml, providing flexibility without duplication.

Real-World Use Cases Where Peky Shines

Multi-Project AI Development

You're maintaining three microservices: a Node.js API, a Rust data processor, and a Python ML pipeline. Each requires different AI agents—Claude Code for the complex Rust refactoring, Codex CLI for quick Node.js endpoints, and a custom GPT-based agent for ML code review. Without Peky, you'd have nine terminal windows, constant context switching, and environment variables scattered across sessions.

With Peky, you create a project-local .peky.yml for each service defining the optimal agent layout. The Node.js project launches with Codex CLI in one pane and your dev server in another. The Rust project opens with Claude Code in a vertical split next to cargo watch. You switch between projects through the dashboard, and each session maintains its state independently. The daemon ensures your long-running Rust analysis continues even when you switch to review Python code.

Team Onboarding and Consistency

Your team of eight engineers struggles with inconsistent AI agent setups. Some use Claude Code globally, others have outdated Codex CLI versions, and onboarding new hires requires a 20-step setup document. Peky solves this by committing .peky.yml to each repository.

New engineers install Peky via Homebrew, clone the repository, and run peky. Instantly, they have the correct agent versions, pre-configured API keys through environment variable expansion, and window layouts matching the team's workflow. The configuration includes project-specific slash commands like /run-tests that broadcast to all agents, ensuring consistent behavior across the team. The native daemon prevents the "it works on my machine" problem by isolating each project's environment.

AI Agent Benchmarking and Comparison

You need to evaluate which AI agent performs best for generating unit tests. The traditional approach involves manually running the same prompt through Claude Code, Codex CLI, and a custom agent, then comparing outputs in separate terminals. This is time-consuming and error-prone.

Peky's broadcast functionality transforms this workflow. You create a layout with three vertical panes, each running a different agent. Typing a single prompt with the broadcast command sends it to all three simultaneously. The scrollback buffer preserves each agent's complete response, and copy mode lets you extract generated code for diff comparison. The persistent daemon means you can leave the benchmark running overnight, collecting responses to dozens of test scenarios without active monitoring.

Microservices Development with AI Assistance

You're building a feature that spans five microservices. Each service needs code generation, API documentation updates, and integration tests. Coordinating this across five separate terminal multiplexers with AI agents is a logistical nightmare.

Peky's project-local configuration enables a master layout that launches all five services simultaneously. Each pane runs the appropriate AI agent with context-aware prompts derived from the project structure. The command palette provides quick actions like "generate integration tests for all services," which triggers a sequential workflow across panes. Mouse support lets you drag and reorganize panes as you focus on different services, and the live preview system shows real-time logs from each microservice next to its AI agent's suggestions.

Step-by-Step Installation and Setup Guide

Prerequisites

Before installing Peky, ensure you have:

• Node.js 16+ (for npm installation) or Homebrew (for macOS/Linux)
• Git for configuration sharing
• Terminal with 256-color support (iTerm2, WezTerm, or modern Terminal.app)
• Go 1.21+ (if building from source)

Installation via npm

The npm package provides cross-platform installation with automatic updates:

# Install globally (requires npm 7+)
npm i -g peky

# Verify installation
peky --version

# Should display: peky version x.x.x

Troubleshooting npm installation:

• If you get EACCES errors, fix npm permissions: sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}
• For Windows users, use Git Bash or WSL2 for full feature support
• Verify the binary is in your PATH: which peky or where peky

Installation via Homebrew (Recommended for macOS/Linux)

Homebrew installation includes native service management:

# Add the custom tap
brew tap regenrek/tap

# Install the package
brew install regenrek/tap/peky

# Start the persistent daemon as a service
brew services start peky

# Verify the service is running
brew services list | grep peky

# Launch the UI
peky

Homebrew advantages:

• Automatic daemon management with launchd/systemd
• Clean uninstallation: brew uninstall regenrek/tap/peky
• Integrated updates: brew upgrade regenrek/tap/peky

Initial Configuration

After installation, initialize your global configuration:

# Create global config directory
mkdir -p ~/.config/peky

# Generate default global config
peky init --global

# Edit to add API keys and preferences
nano ~/.config/peky/config.yml

Project-Local Setup

For team collaboration, always use project-local configuration:

# Navigate to your project
cd ~/projects/my-api

# Initialize local config
peky init --local

# This creates .peky.yml in your project root
ls -la .peky.yml

# Edit the configuration for your stack
nano .peky.yml

# Commit to version control
git add .peky.yml
git commit -m "Add Peky configuration for AI agent orchestration"

First Run Experience

Launch Peky in your project directory:

# Start the UI (automatically connects to daemon)
peky start

# The dashboard appears with your configured layout
# Use mouse or keyboard to interact with panes
# Press ctrl+shift+p for the command palette
# Type / for slash commands

Post-installation verification:

• Check daemon logs: brew services logs peky (Homebrew) or journalctl --user -u peky (Linux)
• Test agent detection: peky doctor (verifies Claude Code, Codex CLI installations)
• Verify mouse support: Click and drag a pane border

Real Code Examples from Peky

Example 1: Installing Peky via npm

This command installs Peky globally through npm, making it available system-wide:

# Install Peky globally using npm
npm i -g peky

# The -g flag installs the package in the global node_modules directory
# This ensures the 'peky' command is available in your PATH
# After installation, you can run 'peky' from any directory

Technical details: The npm package contains pre-compiled Go binaries for multiple platforms. When you run npm i -g peky, npm downloads the correct binary for your OS/architecture and symlinks it to your global bin directory. This approach eliminates Go toolchain requirements for end users while providing automatic updates through npm's versioning system.

Example 2: Homebrew Installation with Service Management

Homebrew installation provides native daemon management:

# Add the custom tap to access Peky formulae
brew tap regenrek/tap

# Install Peky from the custom tap
brew install regenrek/tap/peky

# Start the persistent daemon as a background service
brew services start peky

# Launch the TUI interface
peky

Architecture insight: The brew services start peky command creates a launchd plist (macOS) or systemd service (Linux) that runs the Peky daemon automatically on boot. The daemon listens on a Unix domain socket at /tmp/peky.sock, and the peky command connects to this socket. If the daemon isn't running, the CLI automatically starts it in foreground mode for immediate use.

Example 3: Project-Local Configuration Initialization

This workflow creates a shareable configuration for team collaboration:

# Navigate to your project directory
cd your-project

# Initialize a local Peky configuration
peky init --local

# This generates a .peky.yml file based on project detection
# Edit the configuration to define your layout
nano .peky.yml

# Add the configuration to git for team sharing
git add .peky.yml
git commit -m "Add Peky AI agent orchestration config"

Team workflow explanation: The --local flag scopes the configuration to the current project. When teammates clone the repository and run peky, it automatically detects .peky.yml and uses those settings. This ensures consistent agent versions, API keys (through environment variable references), and window layouts across the entire team, eliminating "works on my machine" issues.

Example 4: Basic YAML Configuration

This configuration defines a simple two-pane layout for a typical web development project:

# .peky.yml - Project-local Peky configuration
# This file defines the session name and pane layout for your project

# Session identifier used in the dashboard
session: my-project

# Layout definition with panes
layout:
  panes:
    # First pane: opens your default editor
    - title: editor
      cmd: "${EDITOR:-nano}"  # Uses $EDITOR env var, falls back to nano
      
    # Second pane: runs development server
    - title: server
      cmd: "npm run dev"      # Command to start your dev server
      split: horizontal       # Splits the screen horizontally

Configuration breakdown:

• session: Names the session for the dashboard. Use descriptive names like api-service or ml-pipeline.
• layout.panes: Array of pane definitions executed in order
• title: Display name in the pane border
• cmd: Shell command to execute. Supports environment variable expansion
• split: Defines pane arrangement. Options: horizontal, vertical, tabbed

Example 5: Advanced Multi-Agent Configuration

This advanced configuration orchestrates multiple AI agents for complex development:

# .peky.yml - Advanced multi-agent orchestration
session: complex-feature

# Global environment variables available to all panes
env:
  OPENAI_API_KEY: "${OPENAI_API_KEY}"
  ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY}"

layout:
  panes:
    # Claude Code for architectural decisions
    - title: claude-architect
      cmd: "claude --context . --prompt 'Analyze system architecture'"
      split: vertical
      
    # Codex CLI for implementation
    - title: codex-implementation
      cmd: "codex --model gpt-4 --watch src/"
      split: horizontal
      
    # Custom agent for documentation
    - title: docs-agent
      cmd: "custom-agent --task document --output docs/"
      env:
        AGENT_SPECIALIZED: "true"
      
    # Development server with live reload
    - title: dev-server
      cmd: "npm run dev"
      split: horizontal
      
    # Terminal for manual commands
    - title: manual-term
      cmd: "$SHELL"

Advanced features explained:

• Environment inheritance: Global env applies to all panes; pane-level env merges with global
• Split strategies: Complex layouts nest splits to create grid arrangements
• Agent specialization: Each pane runs a different AI agent for specific tasks
• File watching: The Codex CLI example includes a watch flag for continuous generation
• Context passing: Claude Code receives project context (.) for informed analysis

Advanced Usage and Best Practices

Performance Tuning for Large Projects

For monorepos with dozens of services, optimize Peky's resource usage:

# In ~/.config/peky/config.yml
daemon:
  max_sessions: 10          # Limit concurrent sessions
  idle_timeout: 300         # Kill idle sessions after 5 minutes
  memory_limit: 2GB         # Per-session memory cap

ui:
  render_interval: 16ms     # 60 FPS rendering
  scrollback_lines: 10000   # Limit scrollback buffer
  mouse_tracking: true      # Enable mouse only if needed

Pro tip: Run peky benchmark to profile layout loading times. For teams, commit a .peky.performance.yml that overrides these settings on CI servers where UI responsiveness matters less than resource conservation.

Layout Builder Patterns

Create reusable layout templates for common scenarios:

# In ~/.config/peky/layouts/web-dev.yml
name: web-development
description: "Standard layout for full-stack web development"
template:
  - title: frontend-agent
    cmd: "claude --context frontend/src"
    split: vertical
    size: 50%
  - title: backend-agent
    cmd: "codex --context backend/src"
    split: vertical
    size: 50%
  - title: database-console
    cmd: "psql ${DATABASE_URL}"
    split: horizontal

Apply templates with: peky start --layout web-development. This pattern reduces configuration duplication across similar projects.

Daemon Management Strategies

The persistent daemon is powerful but requires understanding:

# Check daemon status
peky daemon status

# Restart daemon after config changes
peky daemon restart

# View daemon logs in real-time
peky daemon logs --follow

# Gracefully shutdown all sessions
peky daemon stop --graceful

Best practice: On shared development servers, run the daemon with --user-isolation to prevent session leakage between developers. In production-like environments, use --read-only mode to prevent accidental code generation.

Team Workflow Optimization

Establish team conventions for configuration:

1. Centralize secrets: Use a .env.peky file (gitignored) with API keys, referenced via ${ENV_VAR} in .peky.yml
2. Version compatibility: Specify agent versions in config: cmd: "claude@1.2.3 --task analyze"
3. Shared commands: Define team-wide slash commands in ~/.config/peky/commands.yml:

   commands:
     /security-audit:
       broadcast: true
       prompt: "Perform security audit on current files"
     /generate-docs:
       target: docs-agent
       prompt: "Update documentation based on code changes"
   

Comparison: Peky vs. Traditional Tools

Why Peky wins for AI development: Traditional multiplexers treat all panes as generic terminals. Peky understands it's orchestrating AI agents, providing specialized features like broadcast messaging, agent-specific command palettes, and context-aware layouts. The persistent daemon architecture ensures your expensive AI operations never die with a terminal closure.

Frequently Asked Questions

How does Peky differ from tmux with AI agent scripts?

Tmux provides generic pane management; you must manually configure each AI agent session, manage API keys across panes, and lose work on disconnection. Peky's daemon persists sessions independently of the UI, offers AI-specific features like broadcast messaging and slash commands, and provides project-local configurations that teams can share via git. The Go daemon also offers superior resource management compared to shell scripts.

Can I use Peky with custom AI agents not listed in the README?

Absolutely. Peky is agent-agnostic. Any command-line tool that accepts prompts via stdin or flags can be configured as a pane. Simply define the command in your .peky.yml:

- title: my-custom-agent
  cmd: "python my_agent.py --prompt-file -"

The tool will treat it like any other agent, enabling broadcast and copy mode functionality.

Does Peky work on Windows?

Currently, npm packages are published for macOS and Linux only. Windows users should install from GitHub releases or build with Go:

git clone https://github.com/regenrek/peky
cd peky
go build -o peky cmd/peky/main.go

WSL2 provides full Linux binary support with native Windows filesystem access.

How does the daemon handle API key security?

The daemon never stores API keys itself. It inherits environment from the parent shell that launched it. Recommended practice: store keys in .env.peky (gitignored) and load them via source .env.peky && peky start. For teams, use shell profiles or secret management tools like Vault, referencing keys via ${VAULT_SECRET} in config.

Is Peky suitable for CI/CD pipelines?

While designed for interactive use, Peky can orchestrate agents in CI:

# Headless mode for CI
peky start --headless --config .peky.ci.yml --timeout 300

The daemon runs agents, captures outputs, and exits with appropriate codes. However, for pure automation, direct API calls may be simpler. Peky's strength is interactive development.

What's the performance impact of running multiple AI agents?

Peky itself uses ~50MB RAM and negligible CPU. The daemon adds minimal overhead compared to running agents manually. Resource consumption comes from the AI agents themselves. Peky's idle detection pauses inactive agents, reducing CPU usage by ~70% on average. For memory-constrained systems, set daemon.memory_limit in config to prevent runaway agent consumption.

Can I export agent conversations for documentation?

Yes. Use copy mode to select and yank text, or enable session logging:

# In .peky.yml
session: my-project
logging:
  enabled: true
  path: ./logs/peky-session.log
  format: markdown  # Options: raw, markdown, json

This creates timestamped logs of all agent outputs, perfect for documentation or audit trails.

Conclusion: Why Peky Belongs in Your Toolkit

Peky represents a paradigm shift in AI-assisted development. By transforming fragmented agent workflows into a unified, persistent, and team-friendly interface, it solves problems that traditional terminal multiplexers never considered. The Go-powered daemon architecture ensures reliability, while the Bubble Tea UI framework delivers a modern, responsive experience that makes AI orchestration feel intuitive.

The project's rapid evolution, driven by Kevin Kern's active development and community feedback, positions it as the definitive tool for developers serious about AI integration. Its commitment to zero-configuration setup removes adoption barriers, while the project-local YAML configs provide the sophistication enterprise teams require.

Whether you're a solo developer juggling multiple AI agents or a team lead standardizing workflows across engineers, Peky delivers measurable productivity gains. The time saved from eliminated context switching, persistent sessions, and broadcast commands compounds daily, making it an essential addition to modern development toolchains.

Ready to transform your AI agent workflow? Install Peky today via npm i -g peky or Homebrew, initialize your first project with peky init --local, and experience the future of AI orchestration. Visit the GitHub repository to explore documentation, contribute to the project, and join the growing community of developers who've made AI agent management effortless.