Overview
Themagpie-cli binary provides three modes:
Single Agent
Run a single AI agent prompt without pipeline orchestration.
Full Pipeline
Execute the complete autonomous coding workflow (branch, code, CI, PR).
Blueprint Demo
See the blueprint engine in action with a simple two-step workflow.
Installation
Usage
Single Agent Mode
Run a single AI agent prompt for quick coding tasks:- Uses
MagpieAgent(Goose-powered agent with file/shell access) - Runs in current directory
- Output printed to stdout
- No git operations, no CI, no PR creation
Full Pipeline Mode
Execute the complete autonomous coding workflow:- Creates a feature branch (e.g.,
magpie/add-health-check-endpoint-2) - Classifies task → selects appropriate blueprint (Simple/TDD/Diagnostic)
- Runs agent coding work via blueprint steps
- Executes CI loop (lint + test, up to
MAGPIE_MAX_CI_ROUNDS) - Commits changes with AI-generated commit message
- Pushes to remote and creates PR via
ghCLI - Updates Plane issue if configured
Blueprint Demo Mode
See the blueprint engine in action with a simple demo workflow:- ShellStep: Runs
ls -lain current directory - AgentStep: Summarizes the directory listing in 2-3 sentences
CLI Flags
—pipeline
Run the full autonomous coding pipeline. Syntax:- Must be in a git repository
- Git working directory must be clean (uncommitted changes will cause errors)
ghCLI must be authenticated for PR creation- Environment variables must be configured (see Configuration below)
—trace
Enable JSONL trace logging to.magpie/traces/.
Syntax:
- Debugging pipeline failures
- Performance analysis
- Auditing agent actions
- Building custom monitoring dashboards
—demo
Run the blueprint engine demo (no arguments). Syntax:- Verify Magpie installation
- Understand blueprint execution model
- Test agent connectivity (requires Claude API access)
Configuration
Environment Variables
Create a.env file in your repository root or set environment variables:
.env
Pipeline Config Construction
The CLI buildsPipelineConfig from environment variables:
crates/magpie-cli/src/main.rs:110-157
Examples
Local Development Workflow
Testing Different Blueprints
CI/CD Integration
.github/workflows/magpie.yml
Debugging Agent Behavior
ChatPlatform Implementation
The CLI uses a minimalChatPlatform implementation:
crates/magpie-cli/src/main.rs:92-108
name()returns"cli"for logging/debuggingfetch_history()returns empty (no chat context needed)send_message()is a no-op (output goes to stdout)close_thread()uses default no-op implementation
Troubleshooting
Error: not a git repository
Error: not a git repository
Cause: Running Or set
--pipeline outside a git repository.Fix:MAGPIE_REPO_DIR:Error: uncommitted changes
Error: uncommitted changes
Cause: Git working directory has uncommitted changes.Fix:
Error: gh CLI not authenticated
Error: gh CLI not authenticated
Cause: PR creation requires
gh CLI with valid authentication.Fix:Pipeline runs but CI fails repeatedly
Pipeline runs but CI fails repeatedly
Cause: Agent fixes aren’t resolving test/lint failures within Increase rounds:
MAGPIE_MAX_CI_ROUNDS.Debug:Agent doesn't have file/shell access
Agent doesn't have file/shell access
Cause: Running in single-agent mode (not
--pipeline).Behavior:- Single agent mode: File/shell tools available
- Pipeline mode: Blueprint orchestration with full tool access
Performance Tips
Reduce Pipeline Overhead
Optimize Agent Performance
Parallel Development
Source Files
crates/magpie-cli/src/main.rs— Entry point, argument parsing, all three modes
Next Steps
Discord Adapter
Deploy Magpie to Discord for team collaboration
Teams Adapter
Integrate Magpie with Microsoft Teams
Custom Adapter
Build your own adapter for any platform
Blueprint Engine
Deep dive into blueprint orchestration