revibe-abafc6— agent skill

Purpose

Analyze codebases to understand architecture, file roles, design patterns, execution flows, and system design decisions. Returns structured insights inline and saves agent_context.json for persistent codebase understanding.

Revibe turns any GitHub repository into a complete architecture map — modules, dependencies, call chains, design decisions — in about 2 minutes.

When to Use

• User asks to "analyze", "understand", or "explain" a codebase or repository
• User clones or forks a new repo and wants to understand it quickly
• User says "what does this project do" or "how is this structured"
• User asks about architecture, patterns, or design decisions of a repo
• Another skill needs codebase context to work effectively (use agent mode)

Behavior

Step 1: Extract the Target

Determine the GitHub URL from one of these sources (in priority order):

1. Explicit URL in the message — e.g., https://github.com/owner/repo or owner/repo
2. Current working directory — If the user says "analyze this", "understand this project", or doesn't specify a repo, detect it automatically:

   # Get GitHub URL from current git repo
   REMOTE_URL=$(git remote get-url origin 2>/dev/null)

Convert SSH URLs to HTTPS:

   # [email protected]:owner/repo.git → https://github.com/owner/repo
   if [[ "$REMOTE_URL" == [email protected]:* ]]; then
     REMOTE_URL="https://github.com/${REMOTE_URL#[email protected]:}"
   fi
   # Strip .git suffix
   REMOTE_URL="${REMOTE_URL%.git}"

1. Ask the user — Only if not in a git repo and no URL provided: "Which repository would you like me to analyze?"

When using the current directory, confirm briefly: "Analyzing {repo_name} from your current directory..."

Step 2: Submit for Analysis

# Set up auth
API_KEY="${REVIBE_API_KEY:-}"
AUTH_HEADER=""
if [ -n "$API_KEY" ]; then
  AUTH_HEADER="-H \"X-Revibe-Key: $API_KEY\""
fi

# Submit
RESPONSE=$(curl -s -X POST "https://app-backend.revibe.codes/api/v1/analyze" \
  -H "Content-Type: application/json" \
  ${AUTH_HEADER} \
  -d "{\"github_url\": \"${REMOTE_URL}\"}")

JOB_ID=$(echo "$RESPONSE" | jq -r '.job_id')
STATUS=$(echo "$RESPONSE" | jq -r '.status')

Step 3: Wait for Completion

If status is "completed" or "already_analyzed", skip to Step 4.

Otherwise, poll every 10 seconds (max 3 minutes):

while [ "$STATUS" != "completed" ] && [ "$STATUS" != "error" ]; do
  sleep 10
  POLL=$(curl -s "https://app-backend.revibe.codes/api/v1/analysis/${JOB_ID}/status")
  STATUS=$(echo "$POLL" | jq -r '.status')
  PROGRESS=$(echo "$POLL" | jq -r '.progress // "working"')
  STEPS_DONE=$(echo "$POLL" | jq -r '.steps_completed')
  STEPS_TOTAL=$(echo "$POLL" | jq -r '.steps_total')
  # Show progress: "Analyzing... file_roles (5/10)"
done

If status is "error", tell the user: "Analysis failed. You can try directly at https://revibe.codes"

Step 4: Show Summary

SUMMARY=$(curl -s "https://app-backend.revibe.codes/api/v1/analysis/${JOB_ID}/summary")

Format the response as:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Revibe Analysis: {name}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Architecture: {architecture_pattern}
Language:     {language}
Size:         {total_files} files
Entry point:  {entry_point}

Key Modules:
  {module.name}  — {module.description} ({module.loc} LOC)
  {module.name}  — {module.description} ({module.loc} LOC)
  ...

Patterns: {patterns joined by ", "}
Database: {database.type}, {database.tables} tables    ← only if database exists

agent_context.json saved to current directory.

Explore deeper:
  [1] Architecture diagram
  [2] File roles & structure
  [3] System design Q&A
  [4] Execution flows
  [5] Database schema
  [6] Full interactive analysis → {project_url}

Step 5: Save Agent Context

Always save the agent context file after showing the summary:

curl -s "https://app-backend.revibe.codes/api/v1/analysis/${JOB_ID}/agent-context" \
  > agent_context.json

This file gives the agent (and other skills) structured codebase understanding for future tasks.

Step 6: Handle Drill-Down

When the user picks a number (1-5), fetch that section:

# Map numbers to section names
SECTIONS=("technical_architecture" "file_roles" "system_design_qa" "story_flow" "database_schema")
SECTION_NAME="${SECTIONS[$CHOICE - 1]}"

SECTION_DATA=$(curl -s "https://app-backend.revibe.codes/api/v1/analysis/${JOB_ID}/section/${SECTION_NAME}")

Rendering sections:

• Architecture diagram [1]: Extract data.diagram, render as HTML file with mermaid.js (see Diagram Rendering section), open in browser. Show data.summary and data.layers as a markdown table in terminal.
• File roles [2]: Show as a table — file path, role, description. Group by module if available.
• System design Q&A [3]: Show Q&A pairs. These are the "why" behind architecture decisions.
• Execution flows [4]: Render each flow's diagram as HTML file, open in browser. Show narrative in terminal.
• Database schema [5]: Render ER diagram as HTML file, open in browser. Show table details in terminal.

For option [6], tell the user to open the URL in their browser.

After showing any section, offer to explore another: "Pick another section [1-6] or ask me anything about this codebase."

Agent Mode (Non-Interactive)

When another skill or the agent itself needs codebase context (not a direct user request):

1. Submit analysis (same as above)
2. Wait for completion
3. Fetch and return ONLY the agent_context.json — no formatting, no menu
4. Save to current directory silently

Detection: If the request comes from another skill or is prefixed with context like "I need to understand this codebase to..." — use agent mode.

Diagram Rendering

When a section contains Mermaid diagram data (diagram_mermaid or diagram field), render it as an HTML file and open in the browser:

1. Write the mermaid code to /tmp/revibe-diagram.html:

<!DOCTYPE html>
<html><head><meta charset="utf-8">
<title>TITLE</title>
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
<style>
  body { background: #1a1a2e; display: flex; justify-content: center; padding: 40px; font-family: system-ui; }
  .container { max-width: 1200px; width: 100%; }
  h1 { color: #e0e0e0; font-size: 1.4rem; }
  .mermaid { background: #16213e; border-radius: 12px; padding: 24px; }
  .mermaid svg { width: 100%; }
</style>
</head><body>
<div class="container">
  <h1>TITLE</h1>
  <div class="mermaid">
MERMAID_CODE_HERE
  </div>
</div>
<script>mermaid.initialize({ startOnLoad: true, theme: 'dark' });</script>
</body></html>

1. Open: open /tmp/revibe-diagram.html (macOS) or xdg-open (Linux)
2. In the terminal, show a brief note: "Diagram opened in browser → /tmp/revibe-diagram.html"

Error Handling

Examples

Basic analysis:

User: analyze https://github.com/expressjs/express
→ Submit, wait, show summary card + save agent_context.json

Quick shorthand:

User: /revibe fastify/fastify
→ Resolve to https://github.com/fastify/fastify, analyze

Context for another task:

User: I need to add a feature to this repo, first help me understand it
→ Analyze, show summary, then use agent_context.json for subsequent work

Drill down:

User: show me the architecture diagram
→ Fetch architecture section, render Mermaid as ASCII

Configuration

Get an API key:

1. Sign up at https://revibe.codes
2. Go to Settings → API Keys
3. Click "Generate API Key"
4. Add to OpenClaw config: openclaw config set REVIBE_API_KEY rk_live_xxxxx