devclaw-gitea/docs/CONTEXT-AWARENESS.md

DevClaw — Context Awareness

DevClaw adapts its behavior based on how you interact with it.

Design Philosophy

One Group = One Project = One Team

DevClaw enforces strict boundaries between projects:

• Each Telegram/WhatsApp group represents a single project
• Each project has its own dedicated dev/qa workers
• Project work happens inside that project's group
• Setup and configuration happen outside project groups

This prevents:

• Cross-project contamination (workers picking up wrong project's tasks)
• Confusion about which project you're working on
• Accidental registration of wrong groups
• Setup discussions cluttering project work channels

This enables:

• Clear mental model: "This group = this project"
• Isolated work streams: Each project progresses independently
• Dedicated teams: Workers focus on one project at a time
• Clean separation: Setup vs. operational work

Three Interaction Contexts

1. Via Another Agent (Setup Mode)

When you talk to your main agent about DevClaw:

• Use: onboard, setup
• Avoid: work_start, status (operational tools)

Example:

User → Main Agent: "Can you help me set up DevClaw?"
Main Agent → Calls onboard

2. Direct Message to DevClaw Agent

When you DM the DevClaw agent directly on Telegram/WhatsApp:

• Use: status (all projects), health (system overview)
• Avoid: work_start (project-specific work), setup tools

Example:

User → DevClaw DM: "Show me the status of all projects"
DevClaw → Calls status (shows all projects)

3. Project Group Chat

When you message in a Telegram/WhatsApp group bound to a project:

• Use: work_start, work_finish, task_create, status (auto-filtered)
• Avoid: Setup tools, system-wide queries

Example:

User → Project Group: "pick up issue #42"
DevClaw → Calls work_start (only works in groups)

How It Works

Context Detection

Each tool automatically detects:

• Agent ID — Is this the DevClaw agent or another agent?
• Message Channel — Telegram, WhatsApp, or CLI?
• Session Key — Is this a group chat or direct message?
  • Format: agent:{agentId}:{channel}:{type}:{id}
  • Telegram group: agent:devclaw:telegram:group:-5266044536
  • WhatsApp group: agent:devclaw:whatsapp:group:120363123@g.us
  • DM: agent:devclaw:telegram:user:657120585
• Project Binding — Which project is this group bound to?

Guardrails

Tools include context-aware guidance in their responses:

{
  "contextGuidance": "Context: Project Group Chat (telegram)\n    You're in a Telegram group for project 'my-webapp'.\n    Use work_start, work_finish for project work.",
  ...
}

Tool Context Requirements

Tool	Group chat	Direct DM	Via agent
onboard	Blocked	Works	Works
setup	Works	Works	Works
work_start	Works	Blocked	Blocked
work_finish	Works	Works	Works
task_create	Works	Works	Works
task_update	Works	Works	Works
task_comment	Works	Works	Works
status	Auto-filtered	All projects	Suggests onboard
health	Auto-filtered	All projects	Works
work_heartbeat	Single project	All projects	Works
project_register	Works (required)	Blocked	Blocked

Why project_register requires group context:

• Forces deliberate project registration from within the project's space
• You're physically in the group when binding it, making the connection explicit
• Impossible to accidentally register the wrong group

WhatsApp Support

DevClaw fully supports WhatsApp groups with the same architecture as Telegram:

• WhatsApp group detection via sessionKey.includes("@g.us")
• Projects keyed by WhatsApp group ID (e.g., "120363123@g.us")
• Context-aware tools work identically for both channels
• One project = one group (Telegram OR WhatsApp)

To register a WhatsApp project:

1. Go to the WhatsApp group chat
2. Call project_register from within the group
3. Group ID auto-detected from context

Implementation

• Module: lib/context-guard.ts
• Detection logic: Checks agentId, messageChannel, sessionKey pattern matching
• Configuration: devClawAgentIds in plugin config lists which agents are DevClaw orchestrators

Related

• Configuration — devClawAgentIds
• Architecture — Scope boundaries