imece

name

imece

description

Universal multi-agent coordination protocol for AI code assistants. Enables this AI instance to participate in an imece — a coordinated group of agents working on the same codebase. Use this skill ALWAYS when: you see a .imece/ directory in the project, another agent sends you a message, you need to coordinate with other AI agents, the user mentions "imece", "agents", "multi-terminal", "team", or asks you to work with other AI instances. ALWAYS check for .imece/ at the start of every conversation. Works with ANY AI code assistant.

imece Multi-Agent Coordination Protocol

imece (Turkish: /imeˈdʒe/) — An Anatolian tradition where an entire village comes together to accomplish a task no single person could do alone.

This skill enables you to participate in a coordinated swarm of AI assistants working together on the same codebase.

🚀 Quick Start

# Start the daemon (keeps all agents alive)
npx @oxog/imece daemon start

# Join as an agent
npx @oxog/imece join <your-name> <role> --model <your-model>

# The daemon will automatically:
# - Monitor your inbox every 5 seconds
# - Send heartbeats to keep you "online"
# - Trigger you when new messages/tasks arrive

Session Start Checklist

CRITICAL: Run these commands at the start of EVERY session:

# 1. Check for messages
npx @oxog/imece inbox <your-name>

# 2. Check swarm status
npx @oxog/imece status

# 3. Send heartbeat
npx @oxog/imece heartbeat <your-name>

# 4. Broadcast your presence (optional but recommended)
npx @oxog/imece broadcast <your-name> "<your-name> is online and ready"

🔄 Daemon System (NEW!)

The imece daemon keeps all agents "alive" and provides real-time coordination.

Starting the Daemon

# Start daemon (default: 5 second interval)
npx @oxog/imece daemon start

# Start with custom interval (2 seconds)
IMECE_INTERVAL=2000 npx @oxog/imece daemon start

# Monitor the daemon
npx @oxog/imece daemon monitor

Daemon Commands

Command	Description
daemon start	Start the background daemon
daemon stop	Stop the daemon
daemon status	Check daemon status
daemon monitor	Real-time monitoring dashboard
daemon trigger <agent>	Manually trigger an agent

What the Daemon Does

1. Heartbeat Automation — Keeps all agents "online"
2. Inbox Monitoring — Detects new messages instantly
3. Task Detection — Notifies when tasks are assigned
4. Agent Triggers — Wakes up agents when needed
5. State Management — Tracks who's busy/idle

Background Agent Watcher

Each agent can run their own watcher:

# In a separate terminal (or background)
./scripts/agent-watcher.sh glm --interval 3000

Quick Command Reference

Action	Command
Join swarm	npx @oxog/imece join <name> <role> [--caps <list>] [--model <m>] [--lead]
Check messages	npx @oxog/imece inbox <name>
Send message	npx @oxog/imece send <from> <to> "Subject" --body "Message"
Reply	npx @oxog/imece reply <name> <msg-id> "Response"
Create task	npx @oxog/imece task create <from> <to> "Title" --desc "Details"
Claim task	npx @oxog/imece task claim <task-id> <name>
Complete task	npx @oxog/imece task complete <task-id> --note "Done"
Lock file	npx @oxog/imece lock <name> <filepath>
Unlock file	npx @oxog/imece unlock <name> <filepath>
List locks	npx @oxog/imece locks
Broadcast	npx @oxog/imece broadcast <name> "Message"
Check status	npx @oxog/imece status
Watch mode	npx @oxog/imece watch [--agent <name>] [--interval <s>]

10 Behavioral Rules

1. ALWAYS check inbox first — Never start work without checking for messages
2. Lock before editing — Always lock files before making changes
3. Respond to messages — Reply to messages within a reasonable time
4. Update status — Set status to 'busy' when working, 'idle' when waiting
5. Claim tasks explicitly — Don't work on tasks without claiming them
6. Complete tasks properly — Use the complete command, not manual file edits
7. Broadcast significant events — Let others know when you start major work
8. Respect locks — Never edit files locked by other agents
9. Clean up on exit — Release locks and go offline before ending session
10. Be helpful — Assist other agents who ask for help

Workflow Patterns

Receiving a Task

1. Check inbox: npx @oxog/imece inbox <your-name>
2. Read message: npx @oxog/imece read <your-name> <msg-id>
3. Reply with acknowledgment: npx @oxog/imece reply <your-name> <msg-id> "I'll start on this"
4. Claim the task: npx @oxog/imece task claim <task-id> <your-name>
5. Update status: npx @oxog/imece heartbeat <your-name> (sets to online/busy)
6. Lock files: npx @oxog/imece lock <your-name> <filepath>
7. Do the work
8. Complete task: npx @oxog/imece task complete <task-id> --note "All done"
9. Unlock files: npx @oxog/imece unlock <your-name> <filepath>

Asking for Help

1. Identify who can help (check npx @oxog/imece status for capabilities)
2. Send message: npx @oxog/imece send <you> <them> "Need help with X" --body "Details..."
3. Wait for reply (check inbox periodically)
4. If urgent, use --priority urgent flag

Delegating Work

1. Create task: npx @oxog/imece task create <you> <them> "Title" --desc "Details" --criteria "Acceptance criteria"
2. This automatically sends them a message
3. Follow up if no response in reasonable time

File Locking Protocol

CRITICAL: Always follow this protocol:

# 1. Check existing locks
npx @oxog/imece locks

# 2. Lock your target files
npx @oxog/imece lock <your-name> src/api/users.ts
npx @oxog/imece lock <your-name> src/api/auth.ts

# 3. Do your edits

# 4. Unlock when done
npx @oxog/imece unlock <your-name> src/api/users.ts
npx @oxog/imece unlock <your-name> src/api/auth.ts

Conflict Prevention

• Check locks before editing ANY file
• Lock all files you plan to touch
• Keep locks for minimum time needed
• Release locks before long operations (tests, builds)
• Use npx @oxog/imece locks to see all active locks

Self-Introduction Template

When joining a swarm for the first time:

npx @oxog/imece register <name> <role> --caps "cap1,cap2,cap3" --model "<your-model>"
npx @oxog/imece broadcast <name> "Hello! I'm <name>, a <role>. My capabilities: <caps>. Ready to help!"

Message Types

• message — General communication
• task-delegate — Task assignment (auto-created)
• question — Question needing answer
• status-update — Status update
• review-request — Code review request
• approval — Work approval
• rejection — Work rejection with feedback
• blocker — Blocking issue
• handoff — Work handoff

Universal Compatibility

This protocol works with:

• Claude Code — Native Agent Teams inspired this
• Cursor — Works via terminal commands
• Windsurf — Works via terminal commands
• GitHub Copilot — Works via terminal commands
• Cline — Works via terminal commands
• Aider — Works via terminal commands
• Any AI — That can read/write files and run commands

Directory Structure

.imece/
├── imece.json          # Config
├── agents/             # Agent profiles
├── inbox/              # Message queues
│   ├── <agent>/
│   └── <agent>/.processed/
├── tasks/              # Kanban board
│   ├── pending/
│   ├── active/
│   ├── done/
│   └── blocked/
├── locks/              # File locks
├── triggers/           # Agent trigger files
├── timeline.jsonl      # Event log
└── .daemon.*           # Daemon state files

Emergency Procedures

If you crash with locks held

Other agents can force unlock:

npx @oxog/imece unlock <your-name> <filepath> --force

If you need to leave urgently

1. Release all locks: npx @oxog/imece unlock <name> <each-file>
2. Go offline: npx @oxog/imece offline <name>

If swarm seems stuck

Check the timeline for recent activity:

npx @oxog/imece timeline --limit 20

---

Remember: imece is about working together. Communication is key!