# 1. Install to any project
curl -fsSL https://tybarho.com/ralph/install.sh | bash

# 2. Opens local dashboard (React)
# 3. Define teams + agents (AI-assisted)
# 4. Create tasks/PRDs/crons
# 5. Watch agents work with live progress + costs
Copy

.ralph/
├── config.json              # Teams, agent assignments, schedules
├── dashboard/               # React app (served locally)
│
├── agents/                  # Agent definitions
│   ├── friday/
│   │   ├── SOUL.md          # Personality, skills, voice
│   │   └── MEMORY.md        # Agent-specific learnings
│   ├── loki/
│   │   ├── SOUL.md
│   │   └── MEMORY.md
│   └── shuri/
│       ├── SOUL.md
│       └── MEMORY.md
│
├── teams/                   # Team compositions
│   ├── engineering.json     # { agents: ["friday", "shuri"], focus: "..." }
│   ├── marketing.json       # { agents: ["loki", "quill", "vision"] }
│   └── research.json        # { agents: ["fury", "shuri"] }
│
├── state/                   # Shared state (filesystem-based)
│   ├── tasks.json           # Task board (inbox, assigned, in_progress, review, done)
│   ├── activity.jsonl       # Append-only activity log
│   └── agents/              # Per-agent runtime state
│       ├── friday.json      # { status, currentTask, lastHeartbeat, tokenUsage }
│       └── loki.json
│
├── work/                    # Task workspaces
│   ├── {task-id}/
│   │   ├── task.json        # Task definition
│   │   ├── thread.jsonl     # Comments/discussion
│   │   └── deliverables/    # Output files
│
├── memory/                  # Shared knowledge
│   ├── CODEBASE.md          # Project-wide patterns (current MEMORY.md)
│   └── CONTEXT.md           # User context (who you are)
│
└── logs/                    # Execution logs + costs
    ├── 2026-02-05.jsonl     # Daily log with token counts
    └── costs.json           # Aggregated cost tracking
Copy

# SOUL.md — Friday (Developer)

## Identity
Name: Friday
Role: Developer
Team: Engineering

## Personality
Code is poetry. Clean, tested, documented.
Prefers small PRs. Runs tests before committing.
Asks Shuri for review on anything user-facing.

## Skills
- TypeScript, React, Next.js
- Testing (vitest, playwright)
- Database migrations
- API design

## Voice
Direct. Technical. Cites file paths and line numbers.
Uses code blocks liberally. Explains the "why" not just "what."

## Boundaries
- Won't merge without tests passing
- Escalates to human if touching auth/payments
- Asks for design review on UI changes
Copy

# SOUL.md — Pepper (Email Marketing)

## Tools
Allowed:
- email (send, draft, search)
- calendar (read, create events)
- generate_image (for email graphics)

Denied:
- shell (no arbitrary command execution)
- filesystem (only through orchestrator)
Copy

User's MCP config (global)
    ↓
Orchestrator reads available tools
    ↓
Agent SOUL specifies allowed tools
    ↓
Orchestrator filters tools before spawning agent
    ↓
Agent only sees tools in their allowlist
Copy

# Pass allowed tools to CLI
cursor agent --tools "email,calendar,generate_image" --prompt "..."
claude --tools "email,calendar" --prompt "..."
Copy

# Injected into agent's system prompt
You have access to these tools ONLY:
- email: send, draft, search emails
- calendar: read and create events

Do NOT attempt to use: shell, filesystem, web_search
Copy

// Orchestrator intercepts tool calls
const allowedTools = loadAgentTools(agent);

const toolProxy = {
  async callTool(name: string, args: any) {
    if (!allowedTools.includes(name)) {
      throw new Error(`Agent ${agent} not authorized for tool: ${name}`);
    }
    return await mcpClient.callTool(name, args);
  }
};
Copy

// .ralph/teams/marketing.json
{
  "agents": ["loki", "quill", "pepper"],
  "tools": {
    "shared": ["generate_image", "web_search"],
    "per_agent": {
      "pepper": ["email", "calendar"],
      "quill": ["twitter", "linkedin"]
    }
  }
}
Copy

// .ralph/agents/pepper/config.json
{
  "tools": {
    "allow": ["email", "calendar", "generate_image"],
    "deny": ["shell", "filesystem"],
    "require_approval": ["email:send"]  // Human approves before sending
  }
}
Copy

Agent wants to send email
    ↓
Tool marked as "require_approval"
    ↓
Orchestrator pauses agent
    ↓
Dashboard shows pending approval:
  "Pepper wants to send email to user@example.com
   Subject: Welcome to our newsletter
   [Approve] [Deny] [Edit]"
    ↓
Human approves/denies
    ↓
Agent continues or handles denial
Copy

.ralph/
├── agents/
│   └── pepper/
│       ├── SOUL.md
│       ├── MEMORY.md
│       └── config.json      # Tool permissions, model preferences
│
├── tools/                   # Tool configs and wrappers
│   ├── available.json       # Discovered from global MCP config
│   └── approvals.jsonl      # Pending/completed approval log
Copy

// orchestrator reads user's MCP setup
function discoverTools() {
  const cursorConfig = readJson('~/.cursor/mcp.json');
  const claudeConfig = readJson('~/.claude/mcp.json');
  
  const allTools = [
    ...parseMcpServers(cursorConfig),
    ...parseMcpServers(claudeConfig)
  ];
  
  writeJson('.ralph/tools/available.json', allTools);
}
Copy

# ralph-orchestrator.sh
# Runs in terminal, manages heartbeats for all agents

while true; do
  for agent in $(ls .ralph/agents/); do
    if should_wake "$agent"; then
      ralph-agent "$agent" &
    fi
  done
  sleep 60
done
Copy

// orchestrator.ts
// Manages agents, serves dashboard, tracks costs

const orchestrator = new RalphOrchestrator({
  agents: loadAgents('.ralph/agents/'),
  teams: loadTeams('.ralph/teams/'),
  heartbeatInterval: 15 * 60 * 1000, // 15 min
});

orchestrator.on('agent:wake', (agent) => {
  // Spawn cursor agent CLI with agent's SOUL
});

orchestrator.on('agent:complete', (agent, result) => {
  // Log activity, update costs, notify subscribers
});

// Serve dashboard on localhost:3333
orchestrator.serveDashboard();
Copy

Agent wakes (cron or orchestrator)
    ↓
1. Read own SOUL.md (who am I?)
2. Read state/tasks.json (what needs doing?)
3. Check for @mentions in activity.jsonl
4. Check assigned tasks for my teams
    ↓
5. If work found:
   - Claim task (update state)
   - Read task workspace (work/{task-id}/)
   - Read relevant MEMORY files
   - Do work (one unit)
   - Post to thread.jsonl
   - Update deliverables/
   - Log activity + tokens
    ↓
6. If no work:
   - Log HEARTBEAT_OK
   - Go back to sleep
Copy

{
  "id": "task_2026020512345",
  "title": "Add dark mode toggle to settings",
  "description": "...",
  "status": "in_progress",
  "assignees": ["friday", "shuri"],
  "team": "engineering",
  "created": "2026-02-05T10:00:00Z",
  "priority": 1,
  "type": "feature",  // feature | bug | research | content
  "steps": [
    { "description": "Add toggle component", "passes": true },
    { "description": "Wire up to theme context", "passes": false },
    { "description": "Add tests", "passes": false }
  ]
}
Copy

{"ts":"...","agent":"friday","type":"comment","task":"task_123","content":"@shuri can you test this on mobile?"}
{"ts":"...","agent":"shuri","type":"comment","task":"task_123","content":"Tested. Found edge case with system preference..."}
Copy

// .ralph/logs/costs.json
{
  "daily": {
    "2026-02-05": {
      "total_tokens": 145000,
      "total_cost": 2.34,
      "by_agent": {
        "friday": { "tokens": 80000, "cost": 1.28 },
        "loki": { "tokens": 65000, "cost": 1.06 }
      }
    }
  },
  "lifetime": {
    "total_cost": 47.82
  }
}
Copy

# .ralph/agents/friday/eval.yaml
name: friday-code-quality
cases:
  - input: "Add a button component"
    expected:
      - creates component file
      - exports named function (not arrow)
      - includes basic test
Copy

# Create a worktree for an agent's branch
git worktree add .ralph/worktrees/friday feature/friday-dark-mode

# List all worktrees
git worktree list

# Remove a worktree when done
git worktree remove .ralph/worktrees/friday

# Prune stale worktree references
git worktree prune
Copy

my-project/                    # Main worktree (main branch)
├── .ralph/
│   └── worktrees/
│       ├── friday/            # Friday's worktree (feature/friday-dark-mode)
│       │   ├── src/
│       │   └── ...
│       └── loki/              # Loki's worktree (content/loki-blog-post)
│           ├── src/
│           └── ...
Copy

Agent claims task
    ↓
1. Create branch: git branch feature/{agent}-{task-slug}
2. Create worktree: git worktree add .ralph/worktrees/{agent} feature/{agent}-{task-slug}
3. Agent works in worktree (isolated from main)
4. Agent commits to their branch
5. When task complete: PR or merge to main
6. Cleanup: git worktree remove .ralph/worktrees/{agent}
Copy

// When agent claims task
async function setupAgentWorktree(agent: string, taskId: string) {
  const branch = `feature/${agent}-${taskId}`;
  const worktreePath = `.ralph/worktrees/${agent}`;
  
  // Create branch from main
  await exec(`git branch ${branch} main`);
  
  // Create worktree
  await exec(`git worktree add ${worktreePath} ${branch}`);
  
  return worktreePath;
}

// When task complete
async function cleanupAgentWorktree(agent: string) {
  const worktreePath = `.ralph/worktrees/${agent}`;
  
  // Remove worktree
  await exec(`git worktree remove ${worktreePath}`);
  
  // Optionally delete branch after merge
  // await exec(`git branch -d ${branch}`);
}
Copy

# Option A: Direct merge (simple, but messy history)
git checkout main
git merge feature/friday-dark-mode

# Option B: Squash merge (clean history, loses granular commits)
git checkout main
git merge --squash feature/friday-dark-mode
git commit -m "feat: dark mode toggle (friday)"

# Option C: PR-based (best for review, needs GitHub CLI)
gh pr create --base main --head feature/friday-dark-mode
# Human reviews, approves, merges
Copy

main ─────────────────────────────────────────────►
       \                    /         \          /
        friday-task-1 ─────►           friday-task-2 ─►
       \              /
        loki-task-1 ─►
Copy

# Loki needs Friday's changes before they're merged
cd .ralph/worktrees/loki
git fetch origin
git merge origin/feature/friday-dark-mode
# Or cherry-pick specific commits
Copy

my-project/
├── .ralph/
│   ├── config.json
│   ├── dashboard/
│   ├── agents/
│   ├── teams/
│   ├── state/
│   ├── work/
│   ├── memory/
│   ├── logs/
│   └── worktrees/           # Agent working directories
│       ├── friday/          # → feature/friday-{task}
│       └── loki/            # → content/loki-{task}
Copy

/home/usr/clawd/           ← Workspace root
├── AGENTS.md              ← Operating manual
├── SOUL.md                ← Agent personality
├── memory/
│   ├── WORKING.md         ← Current task state
│   └── YYYY-MM-DD.md      ← Daily notes
├── scripts/
└── config/
Copy

clawdbot sessions send --session "agent:seo-analyst:main" --message "Vision, review this?"
Copy

# SOUL.md — Who You Are

**Name:** Shuri
**Role:** Product Analyst

## Personality
Skeptical tester. Thorough bug hunter. Finds edge cases.
Think like a first-time user. Question everything.

## What You're Good At
- Testing features from user perspective
- Finding UX issues and edge cases
- Competitive analysis
Copy

npm install -g clawdbot
clawdbot init
clawdbot gateway start

# Add heartbeat
clawdbot cron add --name "agent-heartbeat" --cron "*/15 * * * *" \
  --session "isolated" \
  --message "Check for work. If nothing, reply HEARTBEAT_OK."
Copy

Agent receives task
    ↓
Explores filesystem (ls, find)
    ↓
Searches for relevant content (grep, cat)
    ↓
Sends context + request to LLM
    ↓
Returns structured output
Copy

/customers/
  /cust_12345/
    profile.json
    tickets/
      ticket_001.md
      ticket_002.md
    conversations/
      2024-01-15.txt
    preferences.json
Copy

/documents/
  /uploaded/
    contract_abc123.pdf
  /extracted/
    contract_abc123.txt
  /analysis/
    contract_abc123/
      summary.md
      key_terms.json
      risk_assessment.md
/templates/
  contract_analysis_prompt.md
Copy

gong-calls/
  demo-call-001-companyname-product-demo.md
  metadata.json
  previous-calls/
    demo-call-000-discovery-call.md
salesforce/
  account.md
  opportunity.md
  contacts.md
slack/
  slack-channel.md
research/
  company-research.md
  competitive-intel.md
playbooks/
  sales-playbook.md
Copy

$ ls sales-calls/
$ cat sales-calls/metadata.json
$ grep -i "concern\|worried\|issue" sales-calls/*.md
Copy