README
¶
Pagent
CLI tool that orchestrates Claude Code agents to transform PRDs into specs and working code.
flowchart LR
PRD[PRD.md] --> A[architect]
A --> Q[qa]
A --> S[security]
Q & S --> I[implementer]
I --> V[verifier]
V --> O[outputs/]
subgraph Specs
A
Q
S
end
subgraph Code
I
V
end
Quick Start
brew install tuannvm/mcp/pagent
pagent ui
The TUI guides you through selecting a PRD, persona, and running agents:
██████╗ █████╗ ██████╗ ███████╗███╗ ██╗████████╗
██╔══██╗██╔══██╗██╔════╝ ██╔════╝████╗ ██║╚══██╔══╝
██████╔╝███████║██║ ███╗█████╗ ██╔██╗ ██║ ██║
██╔═══╝ ██╔══██║██║ ██║██╔══╝ ██║╚██╗██║ ██║
██║ ██║ ██║╚██████╔╝███████╗██║ ╚████║ ██║
╚═╝ ╚═╝ ╚═╝ ╚═════╝ ╚══════╝╚═╝ ╚═══╝ ╚═╝
From idea to implementation, orchestrated.
Input Persona
> examples/sample-prd.md > Balanced - Standard
Output Action
> ./outputs > ▶ Run
↑ up · ↓ down · / filter · enter select
Or use the CLI directly:
pagent run ./prd.md --sequential -v
Prerequisites
- Claude Code installed and authenticated
Installation
Homebrew (recommended):
brew install tuannvm/mcp/pagent
Alternative installation methods
Binary download:
# Detect OS and architecture automatically
curl -sSL https://github.com/tuannvm/pagent/releases/latest/download/pagent_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/').tar.gz | tar xz
sudo mv pagent /usr/local/bin/
From source (requires Go 1.21+):
git clone https://github.com/tuannvm/pagent && cd pagent && make install
Commands
| Command | Description |
|---|---|
pagent run <prd> |
Run agents on PRD |
pagent ui [prd] |
Interactive dashboard |
pagent status |
Check running agents |
pagent logs <agent> |
View agent output |
pagent message <agent> "msg" |
Send guidance |
pagent stop [--all] |
Stop agents |
pagent init |
Create config file |
pagent mcp |
Run as MCP server |
Common Options
pagent run prd.md --agents architect,qa # Run specific agents
pagent run prd.md --sequential # Run in dependency order
pagent run prd.md --resume # Skip up-to-date outputs
pagent run prd.md --output ./docs/ # Custom output directory
pagent run prd.md --persona minimal # Use minimal persona
Agents
| Agent | Output | Role |
|---|---|---|
| architect | architecture.md |
System design, API, data models |
| qa | test-plan.md |
Test strategy and cases |
| security | security-assessment.md |
Threat model, mitigations |
| implementer | code/* |
Complete codebase |
| verifier | code/*_test.go |
Tests + verification |
Configuration
Run pagent init to create .pagent/config.yaml. Key options:
- persona:
minimal|balanced|production - preferences: API style, testing depth, language
- stack: Cloud, database, CI/CD choices
See docs/tutorial.md for full config reference.
MCP Server
Pagent can run as an MCP (Model Context Protocol) server, enabling integration with Claude Desktop, Claude Code, and other MCP clients.
# Stdio transport (default) - for Claude Desktop
pagent mcp
# HTTP transport - for web integration
pagent mcp --transport http --port 8080
# HTTP with OAuth 2.1 authentication
pagent mcp --transport http --oauth --issuer https://company.okta.com --audience api://pagent
Available MCP Tools:
| Tool | Description |
|---|---|
run_agent |
Run a single agent on a PRD |
run_pipeline |
Run the full agent pipeline |
list_agents |
List available agents |
get_status |
Check running agent status |
send_message |
Send guidance to a running agent |
stop_agents |
Stop running agents |
See docs/tutorial.md for setup instructions.
Claude Code Skill
This repo includes a Claude Code skill (.claude/skills/pagent/SKILL.md) that teaches Claude how to use pagent. When you open this project in Claude Code, it automatically knows pagent commands and workflows.
Documentation
| Doc | Content |
|---|---|
| Tutorial | Step-by-step usage guide |
| Architecture | Technical design and internals |
| Roadmap | Future plans |
Troubleshooting
"timeout waiting for agent" - Check claude --version, increase --timeout 600
"port already in use" - Run pagent stop --all
See docs/tutorial.md#troubleshooting for more.
Contributing
See CONTRIBUTING.md.
Roadmap
Currently supports Claude Code only. Coming next:
- Multi-LLM support - Gemini, Codex, AMP
- Simplified config - Fewer options, smarter defaults
- Better UX - Guided setup, clearer outputs
Recently shipped:
- MCP Server - Integrate with Claude Desktop and MCP clients
See full roadmap.
Acknowledgments
This project is built on AgentAPI by Coder - a brilliant HTTP wrapper for Claude Code that makes agent orchestration possible. Pagent wouldn't exist without it.
License
MIT
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
pagent
command
|
|
|
internal
|
|
|
agent
Package agent provides agent lifecycle management and orchestration.
|
Package agent provides agent lifecycle management and orchestration. |
|
cmd
Package cmd provides the CLI implementation using stdlib flag.
|
Package cmd provides the CLI implementation using stdlib flag. |
|
config
options.go provides shared option definitions for CLI and TUI.
|
options.go provides shared option definitions for CLI and TUI. |
|
mcp
Package mcp provides MCP (Model Context Protocol) server functionality for pagent.
|
Package mcp provides MCP (Model Context Protocol) server functionality for pagent. |
|
runner
Package runner provides the execution logic for running agents.
|
Package runner provides the execution logic for running agents. |
|
state
Package state manages resume state for incremental agent execution.
|
Package state manages resume state for incremental agent execution. |
|
types
Package types contains shared type definitions used across the pagent codebase.
|
Package types contains shared type definitions used across the pagent codebase. |