BetterAgents — Pi.dev Extension

Version: 0.1.1
Status: Ready to use

A Pi.dev extension that integrates 8 specialized AI agents into Pi using the 4-D orchestration methodology.

👉 Quick Start Guide → — Step-by-step installation and usage from zero to AgentX working

What's Built

betteragents-pi/
├── index.ts                    ← Pi ExtensionAPI entry point
├── agents/                     ← 8 agent system prompts
│   ├── critic.md, architect.md, coder.md, tester.md
│   ├── security.md, writer.md, hygienizer.md, devops.md
├── skills/                     ← 8 Pi skill definitions
│   ├── ba-analyze/, ba-design/, ba-generate/, ba-test/
│   ├── ba-secure/, ba-document/, ba-clean/, ba-infra/
├── src/
│   ├── orchestrator.ts         ← AgentX: 4-D pipeline (Deconstruct → Diagnose → Develop → Dispatch)
│   ├── provider.ts             ← OpenRouter real API calls
│   ├── intent-detector.ts      ← Keyword-based intent detection
│   ├── agent-loader.ts         ← Loads agent .md definitions
│   ├── approval.ts             ← 5-level approval gate
│   └── memory.ts               ← Session cost tracking
├── config/
│   └── betteragents.config.json ← Model assignments, approval levels, patterns
├── package.json
└── tsconfig.json

How It Works

1️⃣ Installation

# From this directory:
npm install
npm run build

# Add to your project's .pi/config.json:
{
  "extensions": ["path/to/betteragents-pi"]
}

# Set your OpenRouter API key:
export OPENROUTER_API_KEY="sk-or-v1-..."

# Open Pi
pi

2️⃣ Using AgentX

Three ways to interact with AgentX:

🤖 1. Fully Natural Language (Automatic)

Just describe what you need and AgentX handles it:

"Review this code for bugs"
→ AgentX detects intent → routes to Critic → analyzes → returns result

"Write secure authentication flow"
→ AgentX detects intent → routes to Coder → generates code → returns result

"Scan this for security vulnerabilities"
→ AgentX detects intent → routes to Security → scans → returns findings

🗣️ 2. Conversational (Character-Driven)

AgentX responds as a character, not a robot:

You: "Review this code"
AgentX: "🔍 I've analyzed your code. Here's what I found:
         • Bug in line 42: missing null check
         • Performance issue: O(n²) loop
         • Improvement: use Map instead of Object"

💡 3. Explicit Commands (Fallback)

Type /ba-xxx for direct invocation:

/ba-analyze     → Invoke Critic agent directly
/ba-secure      → Invoke Security agent directly
/ba-generate    → Invoke Coder agent directly
/ba-test        → Invoke Tester agent directly
/ba-document    → Invoke Writer agent directly
/ba-status      → Show session stats and costs

Best practice: Just talk naturally. AgentX listens, detects what you need, and automatically calls the right agent with the right voice and context.

3️⃣ Model Configuration

Default models (from PRD recommendations):

| Agent | Model | Cost | |-------------|--------------------------------------|-----------| | Critic | google/gemini-2.0-flash | $0.075/M | | Architect | google/gemini-2.0-flash | $0.075/M | | Hygienizer | google/gemini-2.0-flash | $0.075/M | | Coder | anthropic/claude-3-5-sonnet-20241022| $3.00/M | | Writer | anthropic/claude-3-5-sonnet-20241022| $3.00/M | | DevOps | anthropic/claude-3-5-sonnet-20241022| $3.00/M | | Tester | google/gemini-1.5-flash | $0.075/M | | Security | google/gemini-1.5-flash | $0.075/M |

Estimated cost: $23.70/month for typical usage (100-200 agent calls/month)

Edit config/betteragents.config.json to change models.

4️⃣ Approval Levels

| Level | Agent | Behavior | |-------|------------------|-----------------------------| | 0 | Critic, Tester | Auto-run (no confirmation) | | 1 | Architect, Writer| Quick Pi.ui.confirm() | | 2 | Coder | Confirm before running | | 3 | Security, DevOps | Require expert review |

AgentX — The 4-D Orchestrator

AgentX is the internal routing and orchestration engine of BetterAgents. It implements the 4-D methodology to automatically detect user intent and route requests to the correct specialized agent.

AgentX operates in three modes simultaneously:

1. Automatic Mode — Listens to natural language, detects intent, routes to the right agent without you asking
2. Conversational Mode — Responds in the agent's voice with personality and context
3. Proactive Mode — Analyzes what you're working on and suggests help before you ask

You don't need to think about which agent to use. Just talk to AgentX like you're talking to a smart assistant, and it figures out the rest.

The 4-D Methodology

Every request follows this pipeline:

User Input
    ↓
[DECONSTRUCT] Extract keywords, assess complexity
    ↓
[DIAGNOSE] Detect intent (analyze/generate/secure/...)
    ↓
[DEVELOP] Select agent + load system prompt
    ↓
[DISPATCH] Check approval
          Call OpenRouter LLM
          Return result
          Track costs + tokens

Example Conversations

Here's what working with AgentX feels like:

Example 1: Automatic + Conversational

You: "Review this authentication logic for security issues"

AgentX: 🔒 I've scanned your code.

Security findings:
  ⚠️ CRITICAL: JWT token stored in localStorage (XSS vulnerability)
  ⚠️ HIGH: No CSRF protection on login endpoint
  ⚠️ MEDIUM: Password reset token doesn't expire
  
Recommendations:
  1. Move JWT to secure httpOnly cookie
  2. Add CSRF middleware
  3. Set 15-min expiration on password reset tokens

Cost: $0.0342 | Tokens: 456

Example 2: Natural Language → Automatic Routing

You: "Write a React hook for handling form state with validation"

AgentX: 💻 I've generated the code.

Here's a custom React hook:

export const useForm = (initialValues, onSubmit) => {
  const [values, setValues] = useState(initialValues);
  const [errors, setErrors] = useState({});
  
  const validate = useCallback((data) => {
    const newErrors = {};
    if (!data.email.includes('@')) newErrors.email = 'Invalid email';
    return newErrors;
  }, []);
  
  const handleChange = (e) => {
    const { name, value } = e.target;
    setValues(prev => ({ ...prev, [name]: value }));
  };
  
  const handleSubmit = (e) => {
    e.preventDefault();
    const newErrors = validate(values);
    if (Object.keys(newErrors).length === 0) {
      onSubmit(values);
    } else {
      setErrors(newErrors);
    }
  };
  
  return { values, errors, handleChange, handleSubmit };
};

Cost: $0.0521 | Tokens: 1,234

Example 3: Explicit Command

You: /ba-document

AgentX: 📝 AgentX Writer ready

Share the code to document:
  • Generate JSDoc comments
  • Write API documentation
  • Create README sections
  • Explain complex logic

You: [paste function]

AgentX: 📝 I've written documentation.

/**
 * Validates email format using RFC 5322 standard
 * @param {string} email - Email address to validate
 * @returns {boolean} True if valid, false otherwise
 * @example
 * validateEmail('[email protected]') // true
 * validateEmail('invalid.email') // false
 */
export const validateEmail = (email) => {
  // Implementation...
};

Cost: $0.0234 | Tokens: 789

What Each Agent Does

Critic

Analyzes code for bugs, quality, security, performance. Scores 0-10.

Architect

Reviews system design, patterns, layering, scalability.

Coder

Generates production-ready code, refactors, implements features.

Tester

Generates unit tests, integration tests, analyzes coverage.

Security

Scans for OWASP vulnerabilities, CVEs, secret leaks.

Writer

Generates JSDoc, README sections, documentation.

Hygienizer

Detects dead code, enforces naming conventions, cleans up repos.

DevOps

Generates Dockerfiles, K8s manifests, CI/CD pipelines, Terraform.

Session Tracking

Type /ba-status to see:

• Total agent runs this session
• Total tokens used
• Total cost ($)
• Cost breakdown by agent

Example output:

📊 BetterAgents Session Stats
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Session ID: abc123
Duration: 45s
Agent Runs: 3
Total Tokens: 1,234
Total Cost: $0.0342

🔍 Agent Runs:
  • Critic: 234 tokens, $0.0081
  • Coder: 567 tokens, $0.0172
  • Tester: 433 tokens, $0.0089

Cost Estimator (When Ready)

Once you have a complete project design, you can calculate costs:

Project: "Build microservice platform"
├─ Estimated PRs/month: 200
├─ Code reviews: 150 (Critic agent)
├─ New features: 30 (Coder agent)
├─ Security audits: 20 (Security agent)

Expected costs:
- CONSERVATIVE (Gemini models): $85/month
- NORMAL (Mixed models): $240/month
- HIGH-END (Claude models): $520/month

To get this estimate, bring your design + ask: "What will this cost?"

File Structure

• agents/ — Agent system prompts (loaded dynamically)
• skills/ — Pi skill metadata (auto-loaded by Pi)
• src/ — Core TypeScript modules
• config/ — Central configuration (models, approval levels, intents)
• index.ts — Pi ExtensionAPI entry point (everything registers here)

Environment Variables

OPENROUTER_API_KEY=sk-or-v1-...  # Required

Troubleshooting

"OPENROUTER_API_KEY not set" → export OPENROUTER_API_KEY="sk-or-v1-..."

"Failed to load agent" → Make sure agents/ directory exists with .md files

"Api call failed" → Check OpenRouter API key is valid: curl -H "Authorization: Bearer $OPENROUTER_API_KEY" https://openrouter.io/api/v1/models

Getting Started

👉 Read the complete step-by-step guide here →

The guide covers:

1. Installing Pi.dev
2. Setting up the BetterAgents extension
3. Getting an OpenRouter API key
4. Configuring Pi
5. Using AgentX naturally
6. Real-world examples
7. Troubleshooting

Quick Summary:

# 1. Install Pi globally
npm install -g @earendil-works/pi-coding-agent

# 2. Install BetterAgents
npm install path/to/betteragents-pi

# 3. Create .pi/config.json
mkdir -p .pi
echo '{"extensions": ["path/to/betteragents-pi"]}' > .pi/config.json

# 4. Set API key
export OPENROUTER_API_KEY="sk-or-v1-..."

# 5. Start Pi
pi

# 6. Talk to AgentX!
pi> Review this code for bugs
pi> Write a function to validate emails
pi> Scan this for security issues
pi> Generate tests for this component

Built as a Pi.dev extension. No separate server. Everything runs inside Pi using OpenRouter for LLM calls.