Skip to main content
What you’ll accomplish: Install Magpie, configure your environment, and run your first end-to-end pipeline from task to pull request.

​
Prerequisites

Before you begin, ensure you have the following tools installed:
Magpie is written in Rust. Install via rustup:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Verify your installation:
rustc --version
# Should show 1.75.0 or higher
Required for both Tier 1 (text generation) and Tier 2 (Goose agent). See Claude Code docs for setup.After installation, verify:
claude --version
The Claude CLI must be authenticated. Run claude once interactively to complete setup.
Git is required for branch operations. The GitHub CLI (gh) handles PR creation.Install Git: git-scm.com/downloadsInstall GitHub CLI:
# macOS
brew install gh

# Linux (Debian/Ubuntu)
sudo apt install gh

# Windows
winget install --id GitHub.cli
Authenticate with GitHub:
gh auth login

​
Install Magpie

1

Clone the repository

git clone https://github.com/your-org/magpie.git
cd magpie
2

Build the project

cargo build --release
First build takes 4-5 minutes due to Goose transitive dependencies (candle, llama-cpp, tree-sitter). Subsequent builds are much faster.
The binary will be available at target/release/magpie-cli.
3

Verify the installation

./target/release/magpie-cli --help
You should see usage information for the Magpie CLI.

​
Run your first task

Let’s test Magpie with a simple agent prompt before running the full pipeline.
1

Run a single prompt

./target/release/magpie-cli "Explain the pipeline module in 2 sentences"
This invokes the Tier 2 agent (Goose) with the prompt. You should see a streaming response explaining the pipeline architecture.
2

Try the blueprint demo

./target/release/magpie-cli --demo
This runs a demo blueprint that:
  1. Lists files in the current directory (Shell step)
  2. Asks the agent to summarize the listing (Agent step)
Example output from the demo:
=== Magpie Blueprint Demo ===

Running blueprint: demo-blueprint

=== Result ===
The directory contains a Rust workspace with four crates...

​
Configure for full pipeline

To run the complete pipeline (task → code → CI → PR), configure these environment variables: 
# Repository configuration
MAGPIE_REPO_DIR=/path/to/your/repo
MAGPIE_BASE_BRANCH=main

# CI commands (customize for your project)
MAGPIE_TEST_CMD="cargo test"
MAGPIE_LINT_CMD="cargo clippy -- -D warnings"
MAGPIE_MAX_CI_ROUNDS=2

# Optional: GitHub org for multi-repo support
MAGPIE_GITHUB_ORG=your-org-name

# Optional: Plane issue tracking
PLANE_BASE_URL=https://plane.yourcompany.com
PLANE_API_KEY=your-api-key
PLANE_WORKSPACE_SLUG=your-workspace
PLANE_PROJECT_ID=your-project-id
Create a .env file in your working directory, and Magpie will automatically load it at startup via dotenvy::dotenv().

​
Run the full pipeline

Now trigger an end-to-end autonomous coding task: 
./target/release/magpie-cli --pipeline "add a health check endpoint to the API"

​
What happens next

1

Task classification

Magpie analyzes your task description and classifies it:
  • Simple: docs, typos, renames → single agent call
  • Standard: features, refactors → TDD blueprint (plan → tests → implement)
  • BugFix: bug fixes → diagnostic blueprint (investigate → regression test → fix)
For “add a health check endpoint”, Magpie will classify this as Standard and use the TDD blueprint.
2

Blueprint execution

The agent executes the TDD blueprint steps:
scan-repo → plan → write-tests → verify-tests-fail 
→ implement → run-tests → lint-check
You’ll see streaming output as the agent:
  • Scans the repository structure
  • Plans the implementation
  • Writes test cases first (red phase)
  • Implements the feature to pass tests (green phase)
  • Runs cargo test and cargo clippy
3

CI loop

After coding completes, Magpie runs your configured test and lint commands. If CI fails, the fix blueprint gives the agent the error output and attempts repairs (up to MAGPIE_MAX_CI_ROUNDS).
4

Commit and PR

Once tests pass:
  1. Branch creation: Creates magpie/add-health-check-endpoint (with collision handling if needed)
  2. Commit: Generates a conventional commit message via Tier 1 Claude call
  3. Push: Pushes to origin with -u flag
  4. PR: Opens a pull request via gh pr create
You’ll see output like:
=== Pipeline Result ===
Status:     Success
CI passed:  true
Rounds:     1
PR:         https://github.com/your-org/your-repo/pull/247

​
Enable tracing (optional)

To debug agent behavior, enable JSONL tracing: 
./target/release/magpie-cli --trace --pipeline "fix the login bug"
This creates .magpie/traces/magpie-trace-YYYY-MM-DD.jsonl with detailed logs of every agent call: 
{
  "step_name": "implement",
  "prompt_preview": "Implement the health check endpoint...",
  "response_preview": "I'll add a new route at /health...",
  "wall_clock_ms": 8234,
  "tool_call_count": 5,
  "timestamp": "2026-03-04T09:15:32Z",
  "events": [
    {"kind": "Text", "content": "I'll add a new route...", "timestamp": "..."},
    {"kind": "ToolRequest", "content": "[ToolRequest: write_file]...", "timestamp": "..."}
  ]
}
Use --trace during development to understand how the agent interprets your tasks and which tools it uses.

​
Next steps

Chat adapters

Set up Discord or Teams to trigger tasks from chat messages

Blueprint engine

Learn how deterministic and agent steps combine in blueprints

Configuration

Explore all environment variables and options

Sandbox options

Run tasks in Daytona sandboxes for isolated execution

​
Common issues

The Claude CLI is not installed or not in your PATH. Follow the Claude Code setup guide.
Install the GitHub CLI:
# macOS
brew install gh

# Linux
sudo apt install gh
Then authenticate: gh auth login
Ensure you’re using Rust 1.75+ and have a C++ compiler installed:
# macOS
xcode-select --install

# Linux (Debian/Ubuntu)
sudo apt install build-essential
Verify the agent has write permissions to MAGPIE_REPO_DIR. The agent uses Goose’s file tools, which operate relative to the working directory set in the session.

Build docs developers (and LLMs) love

Get started for freeTalk to us