macs

Category: Development & Coding | Uploader: Vdc-K | Downloads: 0 | Version: v1.0（Latest）

MACS Protocol v3.1 — The Universal Workbench for AI Agents. Cross-framework work coordination via JSONL event sourcing, capability routing, review chain, escalation, and dead agent reaping.

Changelog: Source: GitHub https://github.com/Vdc-K/macs-protocol

Directory Structure

Current level: Root

📁 .claude-plugin/
- 📄 plugin.json 609 B
📁 .github/
- 📁 ISSUE_TEMPLATE/
  - 📄 bug_report.md 595 B
  - 📄 feature_request.md 424 B
- 📄 PULL_REQUEST_TEMPLATE.md 669 B
📁 .macs/
- 📁 dashboard/
  - 📁 ui/
    
    📄 app.js 13.4 KB
    
    📄 index.html 4.1 KB
    
    📄 style.css 10.6 KB
  - 📄 analyzer.ts 9.8 KB
  - 📄 package-lock.json 22.2 KB
  - 📄 package.json 404 B
  - 📄 server.ts 4.6 KB
  - 📄 tsconfig.json 380 B
- 📁 human/
  - 📄 CHANGELOG.md 282 B
  - 📄 STATUS.md 373 B
  - 📄 TASK.md 622 B
- 📁 protocol/
  - 📄 cli.ts 43.7 KB
  - 📄 engine.ts 53.8 KB
  - 📄 events.jsonl 0 B
  - 📄 human-generator.ts 9.5 KB
  - 📄 package-lock.json 17.3 KB
  - 📄 package.json 488 B
  - 📄 schema.ts 13.3 KB
  - 📄 sdk.ts 10.8 KB
  - 📄 tasks.jsonl 0 B
  - 📄 test.ts 28.3 KB
  - 📄 tsconfig.json 328 B
- 📁 sync/
  - 📁 inbox/
    
    📁 lead/
    
    📄 messages.jsonl 535 B
- 📁 tools/
  - 📁 src/
    
    📄 index.ts 4.1 KB
    
    📄 markdown-indexer.ts 8.1 KB
    
    📄 query-engine.ts 4.7 KB
    
    📄 types-v2.4.ts 7.4 KB
    
    📄 types.ts 1.6 KB
  - 📄 package-lock.json 115.5 KB
  - 📄 package.json 593 B
  - 📄 README.md 3.5 KB
  - 📄 tsconfig.json 427 B
- 📁 transport/
  - 📄 server.ts 9.6 KB
  - 📄 storage.ts 7.2 KB
📁 0-System/
- 📄 knowledge-graph.json 164 B
📁 adapters/
- 📁 aider/
  - 📄 macs-aider.sh 2.1 KB
  - 📄 README.md 2.2 KB
- 📁 codex/
  - 📄 macs-context.md 907 B
  - 📄 README.md 2.2 KB
- 📁 cursor/
  - 📄 README.md 6.3 KB
- 📁 langchain/
  - 📄 pymacs.py 9.5 KB
- 📁 mcp/
  - 📄 macs-mcp-server.ts 18.0 KB
  - 📄 README.md 2.7 KB
- 📁 ollama/
  - 📄 README.md 3.3 KB
- 📁 openclaw/
  - 📄 macs-context.md 2.9 KB
  - 📄 README.md 5.7 KB
  - 📄 swarm.sh 5.4 KB
- 📁 paceflow/
  - 📄 hooks.json 667 B
  - 📄 install.sh 2.3 KB
  - 📄 pre-tool-use.js 1.8 KB
  - 📄 README.md 2.2 KB
  - 📄 session-start.js 1.6 KB
  - 📄 stop.js 2.1 KB
- 📁 plugins/
  - 📄 example-slack-notify.js 1.5 KB
  - 📄 example-webhook.js 1.2 KB
  - 📄 plugin-interface.ts 1.4 KB
  - 📄 README.md 2.8 KB
- 📁 python/
  - 📄 pymacs.py 11.1 KB
- 📁 skill-market/
  - 📄 install.mjs 6.7 KB
- 📁 superpowers/
  - 📄 import-plan.mjs 4.7 KB
  - 📄 README.md 2.9 KB
📁 archive/
- 📄 macs-dimensions-critique.md 12.4 KB
- 📄 RELEASE-CHECKLIST-v2.3.md 5.3 KB
- 📄 RELEASE-NOTES-v2.2.md 8.0 KB
📁 bin/
- 📄 macs.js 1.0 KB
📁 bin-src/
- 📁 dist/
  - 📄 cli.d.ts 1.4 KB
  - 📄 cli.js 49.7 KB
  - 📄 engine.d.ts 6.4 KB
  - 📄 engine.js 57.3 KB
  - 📄 human-generator.d.ts 444 B
  - 📄 human-generator.js 10.8 KB
  - 📄 schema.d.ts 11.0 KB
  - 📄 schema.js 344 B
  - 📄 sdk.d.ts 4.3 KB
  - 📄 sdk.js 10.0 KB
- 📄 cli.d.ts 1.4 KB
- 📄 cli.js 47.1 KB
- 📄 engine.d.ts 3.7 KB
- 📄 engine.js 57.3 KB
- 📄 human-generator.d.ts 444 B
- 📄 human-generator.js 10.8 KB
- 📄 schema.d.ts 10.5 KB
- 📄 schema.js 344 B
- 📄 sdk.d.ts 4.3 KB
- 📄 sdk.js 10.0 KB
📁 demo/
- 📄 run.sh 5.0 KB
- 📄 setup.sh 3.8 KB
📁 docs/
- 📄 BEST-PRACTICES.md 3.5 KB
- 📄 ENTERPRISE-TEAMS.md 11.6 KB
- 📄 EVENT-TRIGGERS.md 5.4 KB
- 📄 FAQ.md 8.5 KB
- 📄 LAUNCH-v5.4.en.md 3.2 KB
- 📄 LAUNCH-v5.4.md 3.1 KB
- 📄 MODEL-ROUTER.md 3.3 KB
- 📄 PLATFORM-COMPATIBILITY.md 5.2 KB
- 📄 QUICKSTART.md 3.4 KB
- 📄 SKILL-CAPSULES.md 8.6 KB
- 📄 TASK-DELEGATION-GUIDE.md 1.7 KB
- 📄 TECHNICAL-FEATURES.md 9.2 KB
- 📄 V2.4-PREVIEW.md 11.1 KB
📁 examples/
- 📁 simple-project/
  - 📄 README.md 3.2 KB
📁 scripts/
- 📄 gen-demo-svg.py 5.9 KB
- 📄 init.sh 1.3 KB
- 📄 macs 2.1 KB
- 📄 setup.sh 1.1 KB
📁 skills/
- 📁 macs/
  - 📄 SKILL.md 3.8 KB
- 📄 registry.json 787 B
📁 templates/
- 📁 github-actions/
  - 📄 macs-ci.yml 1.9 KB
  - 📄 macs-daily-report.yml 1.6 KB
- 📄 CHANGELOG.md 794 B
- 📄 CONTEXT.md 735 B
- 📄 llms.txt 995 B
- 📄 PROJECT-README.md 1.3 KB
- 📄 TASK.md 1.7 KB
- 📄 WEEKLY-REPORT.md 965 B
📄 .gitignore 906 B
📄 AGENT-GUIDE.md 4.3 KB
📄 CHANGELOG.md 9.3 KB
📄 CONTRIBUTING.md 2.1 KB
📄 demo-dashboard-data.json 706 B
📄 DEMO-SCRIPT-v3.md 6.3 KB
📄 DEMO-SCRIPT.md 6.0 KB
📄 demo.svg 10.5 KB
📄 DOGFOOD-REPORT.md 5.2 KB
📄 DOGFOOD-REPORT.zh-CN.md 5.2 KB
📄 install.sh 9.4 KB
📄 LAUNCH-BLOG-POST.md 8.4 KB
📄 LICENSE 1.1 KB
📄 MACS-SPEC.md 10.6 KB
📄 package.json 916 B
📄 README.md 11.2 KB
📄 ROADMAP.md 2.3 KB
📄 SKILL.md 3.8 KB

SKILL.md

---
name: macs
description: MACS Protocol v3.1 — The Universal Workbench for AI Agents. Cross-framework work coordination via JSONL event sourcing, capability routing, review chain, escalation, and dead agent reaping.
author: MACS Community
version: 3.1.0
metadata:
  openclaw:
    requires:
      bins:
        - node
        - npm
        - git
---

# MACS — Multi-Agent Coordination System

> **For Claude Code**
> MACS keeps multiple AI agents in sync on the same project.
> A2A solves how agents talk. MACS solves how agents work together without chaos.

---

## Commands

### `/macs init [name]`
Initialize MACS in the current project.
```bash
macs init my-project
```
Creates `.macs/protocol/`, `.macs/sync/inbox/`, `.macs/human/`.

---

### `/macs status`
Show current project status: tasks, agents, locks.

---

### `/macs register`
Register yourself as an agent.
```bash
macs register claude-sonnet --capabilities backend,testing --model sonnet
```

---

### `/macs claim [task-id]`
Claim a task. Auto-claims best available if no ID given.
```bash
macs claim                                  # auto
macs claim T-001 --agent claude-sonnet      # explicit
```

---

### `/macs start <task-id>`
Mark a task as started.

---

### `/macs done <task-id>`
Complete a task.
```bash
macs done T-001 --summary "Done" --artifacts "src/auth.ts,tests/auth.test.ts"
```

---

### `/macs block <task-id>`
Block a task with reason, optionally escalate.
```bash
macs block T-001 --reason "Need DB choice: PG vs MySQL" --escalate lead-opus
```

---

### `/macs unblock <task-id>`
Unblock a task.
```bash
macs unblock T-001 --decision "Use PostgreSQL"
```

---

### `/macs create <title>`
Create a new task.
```bash
macs create "Add user auth" --priority high --tags auth,backend --depends T-001
```

---

### `/macs impact <file>`
Analyze what changing a file would affect.
```bash
macs impact src/api/users.ts
```

---

### `/macs log`
View recent events (like `git log`).
```bash
macs log --limit 20
```

---

### `/macs inbox <agent-id>`
Check agent inbox.
```bash
macs inbox claude-sonnet --unread
```

---

### `/macs send <from> <to> <message>`
Send a message to another agent.
```bash
macs send claude-sonnet lead-opus "T-001 blocked, need decision on DB" --re T-001
```

---

### `/macs generate`
Regenerate `human/` Markdown from JSONL state.

---

## Typical Agent Session

When starting a session on a MACS project, follow AGENT-GUIDE.md:

```
1. macs register <id> --capabilities ...
2. macs inbox <id> --unread
3. macs status
4. macs claim --agent <id>
5. macs start <task-id>
6. [do the work]
7. macs done <task-id> --artifacts "..."
8. macs generate
```

---

## File Layout

```
.macs/
├── protocol/
│   ├── tasks.jsonl      ← Task events (append-only)
│   ├── events.jsonl     ← Global events (append-only)
│   ├── state.json       ← Current state (auto-rebuilt)
│   └── state.json       ← Agent registry
├── sync/inbox/<id>/     ← Per-agent mailboxes
└── human/               ← Auto-generated Markdown
    ├── TASK.md
    ├── CHANGELOG.md
    └── STATUS.md
```

Never edit `protocol/*.jsonl` or `state.json` directly.
Always use `macs` CLI or `@macs/protocol` SDK.

---

## For SDK users (TypeScript)

```typescript
import { createAgent } from '@macs/protocol'

const agent = createAgent({
  id: 'engineer-sonnet',
  capabilities: ['backend', 'testing'],
})

await agent.loop({
  onTask: async (task) => {
    // do the work
    return { artifacts: ['src/feature.ts'], summary: 'Implemented feature' }
  },
  onMessage: async (msg) => {
    console.log(`Message from ${msg.from}: ${msg.data.content}`)
  },
})
```

## For Python users

See `adapters/python/pymacs.py`.

---

See [README.md](README.md) | [AGENT-GUIDE.md](AGENT-GUIDE.md) | [ROADMAP.md](ROADMAP.md)

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

macs

Directory Structure

SKILL.md

Report

Notice