📐 P3X Architect — Pair-programming AI by default (Claude implements + Codex critiques, ~30-60s on small specs). Add --rup (CLI) or rup:true (MCP) to run the full multi-agent RUP design pipeline (vision, requirements, architecture, risks, acceptance, deploy → 11 roles, 1-3 min) when you actually need a design dossier. Scans your project root and either creates a new project (greenfield) or modifies existing code in place — matching your layout (src/, src-server/, client/server/, monorepo). Code lands at the project root; design artifacts under agents/slug/. v2026.4.110

🌌 Bugs are evident™ - MATRIX️
🚧 This project is under active development!
📢 We welcome your feedback and contributions.

NodeJS LTS is supported

🛠️ Built on NodeJs version

v24.15.0

📝 Description

Pair-programming AI for code changes — driven by your Claude Code + ChatGPT subscriptions (no API keys, no per-call cost).

You hand it a one-paragraph requirement. It scans the project root, decides whether you're greenfield or extending an existing codebase, and either creates a new project at the root or modifies the existing files in place — matching your existing layout (src/, src-server/, client/, server/, monorepo workspaces, …). The actual code lands where it would normally live; a small design artifact (plan.md in pair mode, full dossier in --rup mode) lands under agents/<slug>/.

Two modes

pair mode — default (1 task, 2 AIs, fixed role split)

For 90% of feature work you don't need a multi-phase design dossier — you need code, and a second pair of eyes on it. Pair mode does exactly that. Roles are FIXED per AI to play to each model's strengths:

• Claude = architect, planner, reviewer, risk checker. NEVER writes file content.
• Codex = implementer, refactoring assistant, test writer, code worker. NEVER plans architecture.
• You (human) = final architect + approval authority.

| Step | Role | Provider | | --- | --- | --- | | 1 | pair-planner — produces plan + file_tree (paths + change_notes, no content) | Claude | | 2 | pair-implementer — writes the full content of every file from Claude's plan | Codex | | 3 | pair-reviewer — produces structured issues list (severity / file / fix_hint) | Claude | | 4 | pair-reviser — applies fixes if there are blocking issues (skipped otherwise) | Codex |

Wall-clock: ~30-90s on small specs depending on whether step 4 fires. The cross-provider review catches blind spots a single model would miss — and the role split lets each AI do what it's actually good at instead of asking one to wear every hat. RUP's vision / requirements / architecture / risks / acceptance / deploy phases are skipped here.

rup mode — --rup (full design dossier, 11 roles, 1-3 min)

When you're designing something complex enough to warrant a real design dossier — a new subsystem, a non-trivial migration, an architectural decision — pass --rup (CLI) or rup: true (MCP). The full RUP (Rational Unified Process) pipeline runs across the four classic phases:

| Phase | Roles | Provider chain | | --- | --- | --- | | 1. Inception | vision, vision-reviewer | OpenAI → Claude | | 2. Elaboration | requirements-analyst, architect, risk-analyst, design-reviewer | OpenAI → Claude → OpenAI → Claude | | 3. Construction | implementer, critic ↔ reviser (loop) | Claude, then OpenAI ↔ Claude | | 4. Transition | acceptance-writer, deployment-writer | OpenAI → Claude |

Each phase's outputs feed the next. You get the full dossier (vision, requirements, architecture, risks, acceptance, deploy) under agents/<slug>/ — useful even if you discard the generated code and re-implement by hand.

What you get

Both modes write to two places:

1. The project root itself — actual code. Greenfield projects get a fresh tree at the root; existing codebases get in-place edits matching their layout. Review it with git diff.
2. agents/<slug>/ — the design artifact: small in pair mode, full dossier in --rup mode.

Pair mode output (default)

<project root>/                # ← actual code lands here in place
  ...modified existing files / new files next to siblings...
  agents/<slug>/
    README.md                   # quick summary, role split, mode, file counts, blocking-issue count
    plan.md                     # Claude planner's rationale (greenfield vs modify, layout choices)
    file_tree.json              # what Claude planned for Codex to implement
    changes.json                # { created: [...], modified: [...] }
    issues-round-1.json         # Claude reviewer findings (one round by default; empty array = clean)
    pipeline.json               # per-role token usage + timing

RUP mode output (--rup)

<project root>/                # ← actual code lands here in place
  ...your existing files (modified in place)...
  ...new files (created next to their existing siblings)...
  agents/<slug>/                # ← design dossier only, no nested project copy
    README.md                   # navigation summary, mode (greenfield|modify-in-place), file counts, verdict
    pipeline.json               # per-role token usage + timing + created/modified paths
    inception/
      vision.md
      vision-review-notes.md
    elaboration/
      requirements.json         # structured, MoSCoW-prioritized
      architecture.md
      file_tree.json            # each entry has mode: "create" | "modify" + change_notes
      risks.md
      design-review.md          # reviewer's prose review
      design-findings.json      # specific gaps + verdict
    construction/
      changes.json              # { created: [...], modified: [...] } at the project root
      issues-round-1.json       # critic findings per round
      issues-round-2.json
    transition/
      acceptance.md             # test scenarios + manual checklist
      deploy.md                 # local + production deploy + ops runbook

In both modes, the implementer studies your existing folder layout (src/, src-server/, client/server/, monorepo workspaces, …) before deciding where new files go. New backend code lands next to existing backend code; new frontend code next to the frontend; new admin endpoints next to existing admin endpoints. No nested construction/project/ copy of your repo.

Cheapest path: subscriptions, not API keys

p3x-architect does not call the OpenAI or Anthropic HTTP APIs. It spawns the claude CLI (your Claude Code subscription) and the codex CLI (your ChatGPT subscription) as subprocesses and uses their structured-output flags (--json-schema for claude, --output-schema for codex).

This is deliberate, and it's the whole point:

• A single API run with gpt-5.5 ($5 / $30 per 1M tok) + claude-opus-4-7 ($15 / $75 per 1M tok) costs $2–$10 in RUP mode. Ten runs a month → $20–$100 in API bills.
• A Claude Pro subscription is ~$20/month flat. ChatGPT Plus is ~$20/month flat. You already pay for these. Running the architect against them is $0 marginal cost.
• Trade-off: the CLI route is slower (5–15s per role) and the model is whatever your subscription tier gives you. For the "boss handed me a feature, lay it out" use case, that's fine.
• Pair mode runs 2-3 roles → ~30-60s on small specs. RUP mode runs 11 roles → 1-3 min. Both are $0 on subscriptions.

Prerequisites — install both CLIs and log in once

1. claude (Claude Code) — your Anthropic subscription

Both ship as Node packages, so install is the same on Linux, macOS, and Windows (anywhere Node.js ≥ 18 runs):

npm install -g @anthropic-ai/claude-code
# or, on macOS/Linux: curl -fsSL https://claude.ai/install.sh | bash

Then run claude once interactively — it opens a browser to OAuth into your Claude Pro / Max subscription. After that, claude --print works headlessly without prompts.

2. codex (Codex CLI) — your ChatGPT subscription

npm install -g @openai/codex
# or, on macOS:  brew install codex
# or grab a release binary from https://github.com/openai/codex/releases

Then run codex login once — opens a browser to attach your ChatGPT Plus / Pro subscription. After that, codex exec works headlessly without prompts.

Both CLIs put their auth in your home directory (~/.claude/, ~/.codex/), so once you've logged in any subprocess spawned by p3x-architect picks it up.

3. p3x-architect itself

yarn global add p3x-architect
# or
npm install -g p3x-architect

If you don't want a global install, the MCP entry works on-demand via npx -y -p p3x-architect p3x-architect-mcp — npx pulls the p3x-architect package and runs its p3x-architect-mcp bin. There is no separate p3x-architect-mcp package on npm; both binaries ship inside p3x-architect.

Model selection

Models are picked automatically by the CLIs: claude defaults to opus, codex picks the highest model your account is entitled to (gpt-5.5 as of 2026-04). To override:

ANTHROPIC_MODEL=sonnet            # opus | sonnet | haiku
CODEX_MODEL=gpt-5.5               # only set if you need to force a specific codex model

What if you'd rather use API keys?

You can't, in this version. The HTTP-API providers were removed in favor of the CLI subprocess approach. If that ever needs to come back, it would land behind a flag (e.g. --via-api) — but no plans to do so.

CLI usage

From the project where you want the agents/<slug>/ folder created:

# pair mode (default — fast)
p3x-architect docs/feature-x.md --name feature-x

# inline text in pair mode
p3x-architect --text "Add a /healthz endpoint that returns 200 with the current git sha" --name healthz

# pipe via stdin in pair mode
cat requirement.md | p3x-architect --name nightly-report

# RUP mode — full multi-agent design pipeline
p3x-architect docs/big-redesign.md --name big-redesign --rup

# RUP mode with tighter rounds
p3x-architect spec.md --name auth --rup --max-rounds 1

All flags:

| Flag | Purpose | | --- | --- | | [input] | path to a Markdown file containing the requirement | | -t, --text <s> | inline requirement (alternative to a file) | | -n, --name <slug> | folder name under agents/ (auto-derived if omitted) | | -o, --output <dir> | override output directory | | --rup | run the full RUP multi-agent design pipeline (default off → fast pair mode) | | -r, --max-rounds <n> | maximum critic↔reviser rounds (default 1 in pair mode, 2 in --rup mode) | | -b, --budget <usd> | cumulative USD budget across all roles (default 5, 0 = unlimited) | | --cwd <dir> | project root for agents/<slug>/ (defaults to process.cwd()) |

MCP usage (Claude Code, Cursor, VS Code, …)

The p3x-architect package ships two binaries:

| Binary | Purpose | | --- | --- | | p3x-architect | the CLI you saw above | | p3x-architect-mcp | a Model Context Protocol server (stdio) that exposes the pipeline as a single architect tool |

Both live in the same package — there is no separate p3x-architect-mcp package. Wherever the docs below say npx -y -p p3x-architect p3x-architect-mcp, the -p flag tells npx "install the p3x-architect package, then run the p3x-architect-mcp bin from it."

Claude Code (terminal or VS Code extension)

The Anthropic claude CLI and the Claude Code VS Code extension share the same MCP registry (~/.claude.json), so a single claude mcp add invocation registers the server for both. Run it once from any terminal:

# global install — short form
yarn global add p3x-architect
claude mcp add p3x-architect -- p3x-architect-mcp

# no global install — npx runs it on demand
claude mcp add p3x-architect -- npx -y -p p3x-architect p3x-architect-mcp

# per-workspace registration (lives in .mcp.json next to your project, scoped to that repo)
claude mcp add --scope project p3x-architect -- npx -y -p p3x-architect p3x-architect-mcp

Restart the Claude Code panel in VS Code (or re-open the chat in the terminal) and the architect tool will appear in the tool list. Then ask: "Use p3x-architect to plan and implement this feature: …"

VS Code native MCP (no Claude Code extension)

VS Code 1.95+ ships native MCP support for any MCP-aware extension. Add the file .vscode/mcp.json at your workspace root:

{
    "servers": {
        "p3x-architect": {
            "command": "npx",
            "args": ["-y", "-p", "p3x-architect", "p3x-architect-mcp"]
        }
    }
}

Generic MCP clients (Cursor, Continue, Zed, …)

{
    "mcpServers": {
        "p3x-architect": {
            "command": "npx",
            "args": ["-y", "-p", "p3x-architect", "p3x-architect-mcp"]
        }
    }
}

Local (unpublished) testing

If you cloned this repo and want to drive the MCP from VS Code Claude Code without publishing first, point at the local bin directly:

claude mcp add p3x-architect -- node /absolute/path/to/architect/bin/architect-mcp.js

The MCP exposes one tool — architect — with these parameters:

• requirement (required) — plain-language requirement
• rup (optional, boolean) — set true to run the full RUP pipeline; default false = fast pair mode
• slug (optional) — folder under agents/
• project_root (optional) — absolute path; defaults to MCP server cwd
• max_rounds (optional) — default 1 in pair mode, 2 in RUP mode
• budget_usd (optional) — defaults to ARCHITECT_BUDGET_USD or 5

Pair mode blocks for ~30–60 seconds on small specs; RUP mode for 1–3 minutes. Returns a JSON summary with the pipeline mode, file count, total cost, and per-role token usage (verdict only in RUP mode).

Cost & timing

Because every role spawns your local claude / codex CLI, runtime cost is $0 beyond your existing subscriptions. The --budget flag and usd fields in pipeline.json are kept for forward compatibility with an API-mode that may return later — they will all read 0 in CLI mode.

Wall-clock time is dominated by claude / codex startup (each invocation re-loads its tooling) plus inference latency. Expect:

• 5–15 seconds per role
• Pair mode (default): ~30–90s on a small spec (Claude plan + Codex implement + Claude review + optional Codex revise)
• RUP mode (--rup): 1–3 minutes for the full 11-role pipeline on a small spec; 3–6 minutes on a large one with two critic↔reviser rounds

You can dial down latency with:

• ANTHROPIC_MODEL=sonnet (faster than opus, still strong)
• --max-rounds 0 is not allowed — set --max-rounds 1 to keep just one critic pass with no revision in RUP mode (pair mode already defaults to 1)
• Use the default pair mode unless the change genuinely needs the design dossier

Project structure

src/
  orchestrator.mjs       # mode dispatcher (pair | rup), budget enforcement, output writing
  index.mjs              # public ESM entry — exports architect() and every role
  mcp.mjs                # MCP server (stdio transport)
  scan-project.mjs       # walks the project root and embeds source content for the roles
  providers/
    openai.mjs           # codex CLI subprocess with structured outputs
    anthropic.mjs        # claude CLI subprocess with tool-use schemas
    schema.mjs           # Zod 4 → JSON Schema (strict, additionalProperties:false)
    log-context.mjs      # AsyncLocalStorage for streaming sub-CLI output to the orchestrator
  roles/
    pair-planner.mjs          # pair mode — Claude (plan + file_tree, no content)
    pair-implementer.mjs      # pair mode — Codex (writes full content from plan)
    pair-reviewer.mjs         # pair mode — Claude (issues list)
    pair-reviser.mjs          # pair mode — Codex (applies fixes)
    vision.mjs                # RUP Phase 1 — OpenAI
    vision-reviewer.mjs       # RUP Phase 1 — Claude
    requirements-analyst.mjs  # RUP Phase 2 — OpenAI
    architect.mjs             # RUP Phase 2 — Claude
    risk-analyst.mjs          # RUP Phase 2 — OpenAI
    design-reviewer.mjs       # RUP Phase 2 — Claude
    implementer.mjs           # RUP Phase 3 — Claude
    critic.mjs                # RUP Phase 3 — OpenAI
    reviser.mjs               # RUP Phase 3 — Claude
    acceptance-writer.mjs     # RUP Phase 4 — OpenAI
    deployment-writer.mjs     # RUP Phase 4 — Claude
bin/
  architect.js            # CLI entry
  architect-mcp.js        # MCP server entry
example/
  spec.md                 # tiny CRUD spec for a first end-to-end run

Programmatic API

import { architect } from 'p3x-architect';

// pair mode (default)
const result = await architect({
    requirement: 'Add a /healthz endpoint that returns 200 with the current git sha',
    slug: 'healthz',
    projectRoot: process.cwd(),
    log: console.log,
});

console.log(result.pipelineMode);  // 'pair'
console.log(result.files.length);
console.log(result.usage.totalUsd);

// RUP mode — full design pipeline
const big = await architect({
    requirement: 'Migrate the auth layer from session cookies to JWT...',
    slug: 'auth-migration',
    projectRoot: process.cwd(),
    mode: 'rup',           // or pass rup: true
    maxRounds: 2,
    budgetUsd: 5,
    log: console.log,
});

console.log(big.verdict);          // ready-to-build | fix-then-build | redesign  (RUP mode only)

Every role is also exported individually if you want to run a single one.

Homepage

https://corifeus.com/architect

🌐 Meet Assistant SaaS — meeting.corifeus.com

Don't want to install anything? Try the hosted version at meeting.corifeus.com — full meeting workflow built for European businesses, no setup, no API key, no command line.

What the hosted version offers:

• 21-language live translation during the meeting
• AI summaries, action items, decisions, attendees, key quotes auto-generated after every meeting
• Custom vocabulary — your client / company / industry terms corrected automatically (Pro+ tier)
• Searchable meeting library — find any decision or promise across all your past meetings
• Shareable read-only links — send a clean meeting summary to a client or teammate, no signup needed on their end
• One-click email summary after each meeting
• Premium engine on every plan — no downgraded model, ever
• EU billing — Stripe Tax + VAT-compliant + EUR-priced (Solo €19.99 / Pro €39.99 / Business €99.99 per month, no lock-in)
• GDPR-compliant by default — browser-language auto-detection, no tracking cookies, your meetings stored encrypted

Try the live demo (1 minute free, no signup) or browse the public sample meeting at meeting.corifeus.com/sample.

Corifeus Network

AI-powered network & email toolkit — free, no signup.

Web · network.corifeus.com MCP · npm i -g p3x-network-mcp

• AI Network Assistant — ask in plain language, get a full domain health report
• Network Audit — DNS, SSL, security headers, DNSBL, BGP, IPv6, geolocation in one call
• Diagnostics — DNS lookup & global propagation, WHOIS, reverse DNS, HTTP check, my-IP
• Mail Tester — live SPF/DKIM/DMARC + spam score + AI fix suggestions, results emailed (localized)
• Monitoring — TCP / HTTP / Ping with alerts and public status pages
• MCP server — 17 tools exposed to Claude Code, Codex, Cursor, any MCP client
• Install — claude mcp add p3x-network -- npx p3x-network-mcp
• Try — "audit example.com", "why do my emails land in spam? test [email protected]"
• Source — patrikx3/network · patrikx3/network-mcp
• Contact — patrikx3.com · donate

❤️ Support Our Open-Source Project

If you appreciate our work, consider ⭐ starring this repository or 💰 making a donation to support server maintenance and ongoing development. Your support means the world to us—thank you!

🌍 About My Domains

All my domains, including patrikx3.com, corifeus.eu, and corifeus.com, are developed in my spare time. While you may encounter minor errors, the sites are generally stable and fully functional.

📈 Versioning Policy

Version Structure: We follow a Major.Minor.Patch versioning scheme:

• Major: 📅 Corresponds to the current year.
• Minor: 🌓 Set as 4 for releases from January to June, and 10 for July to December.
• Patch: 🔧 Incremental, updated with each build.

🚨 Important Changes: Any breaking changes are prominently noted in the readme to keep you informed.

P3X-ARCHITECT Build v2026.4.110