@wizdear/atlas-code

AI-powered multi-agent engineering system for pi-coding-agent. Automates feature development from requirements to implementation through role-based agent orchestration.

Overview

Given a natural-language requirement, Atlas Code decomposes it into features, assigns specialized agents, and executes an end-to-end pipeline: Discovery → Planning → Design → Implementation → Testing → Review → Documentation.

Prerequisites

• Node.js >= 20.0.0
• An LLM provider account — OAuth subscription (Claude Pro/Max, ChatGPT Plus, etc.) or an API key (Anthropic, OpenAI, Google, etc.)

Installation

macOS / Linux

1. Install Node.js if not present:

   # macOS (Homebrew)
   brew install node
   
   # Ubuntu / Debian
   curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
   sudo apt-get install -y nodejs

2. Run setup:

   npx @wizdear/atlas-code setup

3. Navigate to your project and launch:

   cd /path/to/your/project
   acode

Windows (PowerShell — native)

1. Install Node.js if not present, then run setup:

   if (-not (Get-Command node -ErrorAction SilentlyContinue)) {
     winget install OpenJS.NodeJS.LTS --accept-package-agreements --accept-source-agreements
   }
   npx @wizdear/atlas-code setup

2. Open a new terminal (so PATH picks up the installed commands), navigate to your project, and launch:

   cd C:\path\to\your\project
   acode

Windows (WSL + VS Code — recommended)

WSL provides a Linux environment inside Windows, avoiding PowerShell compatibility issues. This is the recommended setup for Windows users.

Quick start:

# 1. Install WSL (PowerShell as Administrator)
wsl --install    # then reboot

# 2. In Ubuntu terminal: install Node.js via nvm (no sudo needed)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install 22

# 3. Install Atlas Code
npx @wizdear/atlas-code setup

# 4. Open project in VS Code
cd ~/projects/my-project && code .

# 5. In VS Code terminal: launch
acode

For detailed step-by-step instructions, VS Code keybindings setup, troubleshooting (including migrating from sudo-based installs), see the WSL + VS Code Setup Guide.

Authentication & Model Selection

After launching, authenticate with your LLM provider:

• OAuth subscription (Claude Pro/Max, ChatGPT Plus, etc.): type /login and select a provider
• Atlas SSO: type /login, select AI Atlas (SSO), authenticate via browser
• API key: set an environment variable before launching

  export ANTHROPIC_API_KEY="sk-ant-..."

Once authenticated, type /model (or press Ctrl+L) to select a model.

As a Standalone SDK (programmatic, CI/CD)

1. Create a Node.js project (or use an existing one):

   mkdir my-project && cd my-project
   npm init -y

2. Install:

   npm install @wizdear/atlas-code

3. Set your LLM API key:

   export ANTHROPIC_API_KEY="sk-ant-..."

4. Create a script (e.g. vibe-fix.mjs):

   import { createVibeSession } from "@wizdear/atlas-code";
   
   const vibe = await createVibeSession({
     projectRoot: process.cwd(),
     model: { provider: "anthropic", id: "claude-sonnet-4-6" },
     apiKey: process.env.ANTHROPIC_API_KEY,
   });
   
   const result = await vibe.fixAndWait("TypeError at src/user-service.ts:42");
   console.log(result.status); // "done" | "failed" | "blocked"

5. Run:

   node vibe-fix.mjs

Keyboard Shortcuts

| Key | Action | |-----|--------| | Ctrl+O | Expand/collapse messages | | Ctrl+G | Open external editor | | Ctrl+L | Select model | | Ctrl+T | Change thinking level | | Ctrl+C | Interrupt (press twice to quit) | | Shift+Enter | Newline (Enter sends) | | Esc | Abort running pipeline |

VS Code conflict: Ctrl+O conflicts with "Open File". Add this to VS Code keybindings.json to disable it when terminal is focused:

{ "key": "ctrl+o", "command": "-workbench.action.files.openFile", "when": "terminalFocus" }

Workflow Types

| Type | Use Case | Pipeline | |------|----------|----------| | new_feature | New functionality | Discovery → Plan → Design → Implement → Test → Regression → Review → Document | | enhancement | Improve existing code | Discovery → Analyze → Plan → Design → Implement → Test → Regression → Review | | bugfix | Fix a bug | Discovery → Investigate → Diagnose → Implement → Test → Regression → Review | | refactor | Restructure code | Discovery → Analyze → Design → Implement → Regression → Review | | (default) | No subcommand — system infers type per feature | Analyzes requirements and assigns the appropriate type per feature |

Agent Roles

| Agent | Role | Permission | |-------|------|------------| | Discovery | Refines requirements through conversational Q&A | READ | | Project Analyzer | Scans project structure, tech stack, conventions | READ | | Planner | Decomposes requirements into features with dependencies | READ | | Analyzer | Assesses impact on existing codebase | READ | | Architect | Designs interfaces and component structure | READ+WRITE | | Developer | Implements code changes | FULL | | Tester | Writes and runs tests | FULL | | Diagnostician | Investigates and diagnoses bugs | READ+EXEC | | Reviewer | Reviews code quality and architecture compliance | READONLY | | CI/CD | Branch and merge management | GIT CLI | | System Architect | Designs system-wide architecture and component contracts | READ+WRITE | | Standards Enricher | Injects project-specific standards from context | READ | | Documenter | Updates project docs and README | WRITE | | Recover | Analyzes artifacts to reconstruct lost pipeline state | READ+EXEC |

pi Extension Usage

# Auto-detect workflow type (no subcommand needed)
/vibe "Add user authentication with OAuth2"

# Explicit workflow types
/vibe new "Build a REST API for user management"
/vibe enhance "Add rate limiting to API endpoints"
/vibe fix "Login returns 500 when token expires" --issue 127
/vibe refactor "Split auth module into separate services"

# Project setup
/vibe init          # Initialize .vibe/ directory with standards + skills
/vibe analyze       # Analyze project (project-context.md + knowledge graph)
/vibe config        # Interactive settings editor
/vibe reset         # Delete all .vibe/ contents and start fresh
/vibe recover       # Recover from failed pipeline state

# Knowledge graph & onboarding
/vibe dashboard     # Open interactive knowledge graph dashboard in browser
/vibe onboard       # Generate onboarding document from knowledge graph
/vibe bootstrap     # Bootstrap existing codebase into feature structure

# Observability (Trace Companion)
/vibe trace              # Show trace overview (spans, cost, tool usage)
/vibe trace show <id>    # Inspect a specific span
/vibe trace export       # Export run/feature/span as self-contained HTML
/vibe trace-build        # Rebuild trace index from checkpoint data
/vibe stats              # Aggregate usage statistics
/vibe cost               # Cost breakdown by feature/role/span

# Standards management
/vibe standard "UI는 Ant Design을 사용한다"     # Add standard from text
/vibe standard ./docs/design-guide.md           # Add standard from file
/vibe standard list                             # Show all standards
/vibe standard remove ui-standards.md           # Remove a standard

# Pipeline control
/vibe status                 # Show active pipelines
/vibe status feat-001        # Show feature detail
/vibe pause feat-001         # Pause after current step
/vibe resume                 # Resume from saved state
/vibe resume feat-001        # Resume specific feature
/vibe steer feat-001 "Use PostgreSQL instead of MySQL"

# Without /vibe — regular AI coding assistant
this code has a bug, can you find it?

SDK Usage

The SDK provides programmatic access to pipelines without the pi TUI. Useful for CI/CD integration, scripting, and automated workflows.

Basic Example

import { createVibeSession } from "@wizdear/atlas-code";

const vibe = await createVibeSession({
  projectRoot: "/path/to/project",
  model: { provider: "anthropic", id: "claude-sonnet-4-6" },
  apiKey: process.env.ANTHROPIC_API_KEY!,
});

// Stream events
for await (const event of vibe.newFeature("Add user authentication")) {
  console.log(`[${event.type}] ${event.featureId}`);
}

// Or wait for completion
const result = await vibe.newFeatureAndWait("Add user authentication");
console.log(result.status); // "done" | "failed" | "blocked"

Bug Fix

const result = await vibe.fixAndWait("TypeError at src/user-service.ts:42", {
  issueRef: "#127",
});

Gate Policies

Control how quality gates (test, review, regression) are handled:

// Auto-approve all gates (default)
const vibe = await createVibeSession({
  projectRoot: "/path/to/project",
  model: { provider: "anthropic", id: "claude-sonnet-4-6" },
  apiKey: process.env.ANTHROPIC_API_KEY!,
  gatePolicy: "auto_approve",
});

// Auto-reject all gates
const vibe2 = await createVibeSession({
  // ...
  gatePolicy: "auto_reject",
});

// Custom gate handler
const vibe3 = await createVibeSession({
  // ...
  gatePolicy: async (summary) => {
    console.log("Gate:", summary);
    return { passed: true, action: "approved" };
  },
});

CI/CD Self-Healing

Use the SDK in CI/CD pipelines to automatically fix failing tests:

import { createVibeSession } from "@wizdear/atlas-code";

const vibe = await createVibeSession({
  projectRoot: process.cwd(),
  model: { provider: "anthropic", id: "claude-sonnet-4-6" },
  apiKey: process.env.ANTHROPIC_API_KEY!,
  gatePolicy: "auto_approve",
});

const result = await vibe.fixAndWait(
  `Test failure in user-service.test.ts: Expected 200 but got 500.
   Stack trace: TypeError: Cannot read property 'id' of undefined at UserService.getUser`
);

if (result.status === "done") {
  console.log("Fix applied successfully");
}

SDK API Reference

createVibeSession(options): Promise<VibeSession>

| Option | Type | Description | |--------|------|-------------| | projectRoot | string | Absolute path to the project root | | model | SdkModelSpec | Provider and model ID (e.g. { provider: "anthropic", id: "claude-sonnet-4-6" }) | | apiKey | string | LLM API key | | gatePolicy | GatePolicy | "auto_approve" (default), "auto_reject", or custom callback | | logger | VibeLogger | Custom logger (noop by default) |

VibeSession Methods

| Method | Description | |--------|-------------| | newFeature(requirement) | Run new_feature pipeline, yields VibeEvent | | enhance(requirement, options?) | Run enhancement pipeline | | fix(description, options?) | Run bugfix pipeline | | refactor(purpose, options?) | Run refactor pipeline | | newFeatureAndWait(requirement) | Run and wait for VibeSessionResult | | enhanceAndWait(requirement, options?) | Run and wait | | fixAndWait(description, options?) | Run and wait | | refactorAndWait(purpose, options?) | Run and wait |

VibeSessionResult

interface VibeSessionResult {
  status: "done" | "failed" | "blocked";
  completed: string[];   // completed feature IDs
  failed: string[];      // failed feature IDs
  skipped: string[];     // skipped feature IDs
  events: VibeEvent[];   // all events from the run
}

Autonomy Levels

| Level | Behavior | |-------|----------| | full_auto | Runs to completion, no user intervention | | gate_auto | Pauses at quality gates for approval (recommended) | | step_by_step | Pauses at every step for approval |

Cost Optimization

By default every agent role uses the pipeline-wide model that pi was started with. You can route mechanical roles (reviewer, tester, cicd) to cheaper models without changing the high-value reasoning roles (planner, systemArchitect, architect, developer, diagnostician, discovery) by setting modelOverrides in .vibe/config.json:

{
  "modelOverrides": {
    "reviewer": { "provider": "anthropic", "id": "claude-sonnet-4-6" },
    "tester":   { "provider": "anthropic", "id": "claude-sonnet-4-6" },
    "cicd":     { "provider": "anthropic", "id": "claude-haiku-4-5" }
  }
}

Each entry is a { provider, id } reference resolved against the runtime model registry at agent creation time.

• The override resolution is lazy and graceful: if the referenced model is not registered, has no API key, or fails to load, the agent silently falls back to the default model and a warn entry is written to .vibe/logs/. The pipeline never throws on a misconfigured override.
• Roles not listed in modelOverrides use the default model unchanged.
• The recommended preset above (Sonnet for reviewer/tester, Haiku for cicd) has been measured against the atlas-work reference project to reduce per-feature spend by roughly 50–60% with no observed quality regression on mechanical roles. Always validate the impact on your own project before committing to a preset.
• Available agent roles for modelOverrides: planner, architect, developer, tester, reviewer, cicd, analyzer, diagnostician, discovery, projectAnalyzer, documenter, standardsEnricher, systemArchitect, recover.

To verify a model is registered, run /model inside pi.

Project Structure

After /vibe init, the following structure is created:

.vibe/
├── config.json              # Project configuration
├── project-context.md       # Auto-generated project analysis
├── knowledge-graph.json     # Knowledge graph (nodes, edges, layers, tour)
├── graph-meta.json          # Graph analysis metadata (commit hash, timestamp)
├── requirements.md          # Refined requirements from Discovery
├── plan.json                # Feature decomposition plan
├── orchestration-state.json # Resume state (auto-managed)
├── traces/                  # Runtime observability data
│   ├── runs.jsonl           # Pipeline run records
│   ├── spans.jsonl          # Per-agent span records (timing, tokens, cost)
│   ├── events.jsonl         # Live event stream (text deltas, tool calls)
│   ├── prompts/             # Content-addressed system prompts (<sha256>.txt)
│   └── exports/             # HTML exports from /vibe trace export
├── graph-docs/              # Markdown docs generated from graph (for QMD search)
├── standards/               # 11 standard template files
│   ├── coding-style.md
│   ├── coding-conventions.md
│   ├── tech-stack.md
│   ├── architecture-principles.md
│   ├── testing-standards.md
│   └── ...
├── features/                # Per-feature artifacts
│   ├── feat-001/
│   │   ├── spec.md
│   │   ├── design.md
│   │   ├── test-report.md
│   │   ├── review.md
│   │   └── status.json
│   └── feat-002/
│       └── ...
└── logs/                    # Daily log files
    └── 2025-01-15.log

Standards System

Atlas Code ships with 11 standard templates that are automatically loaded per agent role. Standards are enriched with project-specific context after Discovery and Planning phases.

| Standard | Applied To | |----------|------------| | coding-style.md | Developer, Reviewer | | testing-standards.md | Tester | | architecture-principles.md | Architect, Reviewer | | security-policy.md | Developer, Reviewer | | git-workflow.md | CI/CD | | ... | ... |

Edit files in .vibe/standards/ to customize project conventions. Use /vibe standard to add standards from text descriptions or existing documents without manually editing files.

Structured Discovery

When structuredDiscovery is enabled (default: true), the Discovery phase produces structured artifacts instead of a monolithic requirements document:

1. Q&A — Clarifying questions, project type detection, assumption confirmation
2. 📱 Screens — ASCII wireframe boxes for each screen (UI projects only)
3. 🔄 Flows — Vertical flowcharts for user scenarios
4. ⚡ Capabilities — System capabilities with acceptance criteria in business language
5. Validation — Cross-artifact consistency check (orphan screens, missing references)
6. Synthesis — Final requirements.md generated from validated artifacts

Each phase presents artifacts for user review (Approve/Modify/Cancel). Artifacts are rendered in the user's conversation language (e.g., Korean input → Korean screen/flow/capability names).

Configure in .vibe/config.json:

{
  "discovery": {
    "structuredDiscovery": true,
    "itemByItemReview": true
  }
}

MCP Server Integration

Atlas Code includes pi-mcp-adapter for connecting to MCP (Model Context Protocol) servers. It is automatically installed during setup.

Project-level configuration

Create .pi/mcp.json in your project root:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

Global configuration

Create ~/.pi/agent/mcp.json with the same format. Project config overrides global.

Import existing configs

If you already use MCP with other tools:

{
  "imports": ["cursor", "claude-code", "claude-desktop", "vscode"],
  "mcpServers": {}
}

Usage

The adapter registers a single mcp() proxy tool (~200 tokens) instead of registering every tool individually:

mcp({ search: "screenshot" })         # Search available tools
mcp({ tool: "take_screenshot", args: '{"format":"png"}' })  # Call a tool
mcp({ server: "chrome-devtools" })     # List tools from a server

For frequently used tools, promote them to direct registration:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "directTools": ["search_repositories", "get_file_contents"]
    }
  }
}

Servers are lazy by default — they start on first tool call and disconnect after 10 minutes of idle time. See the pi-mcp-adapter documentation for full configuration options.

Key Features

• Multi-agent orchestration: Features execute in dependency order with parallel-safe coordination
• Quality gates: Configurable approval points for requirements, plans, tests, reviews, and merges
• Automatic retry + rollback: Failed tests and reviews trigger automatic rollback to Developer with feedback loops. Artifacts are archived with timestamps before overwriting on retry.
• Session persistence: Abort and resume workflows across sessions with /vibe resume
• Vibe Companion: Browser-based UI with Artifacts tab (visual mockups) and Trace tab (real-time per-agent observation with Conversation/Live Transcript/Raw Events views, markdown rendering via marked.js)
• Observability: Runtime trace writer captures per-agent spans, token usage, tool calls, and cost. Post-mortem HTML exports and inspector commands (/vibe trace, /vibe stats, /vibe cost)
• Greenfield scaffolding: System Architect produces a directory manifest (scaffold.json), pre-creating the project structure before implementation starts
• Context compaction: Automatic conversation history compaction to stay within context limits
• Standards enrichment: Project-specific coding standards injected per agent role
• Traceability: Requirements mapped to features with unmapped requirement warnings
• Knowledge graph dashboard: Interactive visualization with hierarchical drill-down (Layer → File → Function), smart filtering, importance ranking, and focus mode
• Multi-language import resolution: Reverse path matching resolves Go, Python, Java, Rust imports — not just relative JS/TS paths
• Project memory (QMD): Semantic search over git commit history to prevent repeating mistakes
• Skill discovery: Agents discover and use project-specific skills
• Pipeline UI: Real-time step progress with activity log in the terminal
• Telegram remote control: Monitor and control pipelines from anywhere
• Programmatic SDK: createVibeSession() for CI/CD and scripting without the TUI

Environment Variables

| Variable | Description | |----------|-------------| | VIBE_DEBUG_PAUSE | When set, pauses before stopping the Trace Companion server on pipeline completion. Shows the server URL and waits for user confirmation. Useful for inspecting trace data after a run finishes. |

License

MIT