Communication

Gee-Code can reach you outside the terminal — via SMS, email, or even a phone call. It can also bridge to the Gee backend for services like web search, email, calendar, and cloud storage. These tools are especially important for autonomous Gees that need to report results, ask questions, or escalate issues without a human watching the terminal.

SendNotification

The primary way a Gee communicates with you directly.

SendNotification(message="Build completed. Ready to deploy.", channel="sms")
SendNotification(message="Weekly report attached.", channel="email", subject="Week of Feb 3")
SendNotification(message="Production error in auth service.", channel="voice")

Parameters

Parameter	Default	Description
message	(required)	The message body
channel	"sms"	Delivery channel: sms, email, or voice
subject	—	Email subject line (email channel only)
priority	"normal"	low, normal, or high — high-priority SMS is prefixed with [URGENT]
gee_name	(auto-resolved)	Which Gee identity to send from

Identity Resolution

The system determines which Gee is sending through a resolution chain:

1. Explicit gee_name parameter — used directly if provided
2. Environment variables — GEE_MODE_NAME, GEE_ACTIVE_MODE, or GEE_NAME (set automatically in BYOP and MCP contexts)
3. In-process mode — the currently active mode in the local runtime
4. Fallback — defaults to "gee"

You rarely need to set gee_name manually. It exists for edge cases where a Gee sends on behalf of a different identity.

Reply Routing

Every outbound SMS includes a reply code derived from the Gee’s name. The algorithm splits the name on hyphens and underscores, then takes the first letter of each part:

Gee Name	Reply Code
trip-planner	TP
code-reviewer	CR
my-awesome-gee-thing	MAGT
analyst	ANA (single word: first 3 characters)
gee	GEE (special case)

When you reply to the SMS, prefix your message with the reply code. The gateway matches it to the correct Gee and routes your response to its inbox. This means multiple Gees can message you simultaneously without replies getting crossed.

SMS messages are also prefixed with the Gee’s name in brackets — [trip-planner] Your report is ready — so you always know who’s texting. High-priority messages add an [URGENT] flag.

Voice Calls

The voice channel initiates a real-time AI phone call via Twilio. Before placing the call, the system enriches the message with the Gee’s current objectives summary:

Your original message

--- Current Objectives ---
1. [high] Analyze Q1 sales trends (in progress)
2. [medium] Review budget allocations (pending)

This gives the voice agent enough context to hold an informed conversation about what the Gee has been working on. After the call, a summary and transcript are written back to the Gee’s inbox.

Outbox Audit Trail

All notifications are logged to the Gee’s outbox at ~/.gee-code/modes/{gee_name}/comms/outbox.jsonl. Each line is a JSON object:

{
  "id": "notif-20260211T143022",
  "type": "notification",
  "from_mode": "analyst",
  "to_mode": "user",
  "subject": "(sms)",
  "body": "Your report is ready.",
  "timestamp": "2026-02-11T14:30:22+00:00",
  "metadata": { "channel": "sms", "priority": "normal" }
}

The outbox is append-only and write-once — entries are never modified. This provides a complete audit trail of everything a Gee has sent you, across all channels.

GeeConnect

A bridge to Gee server capabilities that aren’t available locally. Use this when you need web search, email operations, cloud storage, Google Drive access, or other backend services.

GeeConnect(service="search", action="web", params={"query": "python async patterns"})
GeeConnect(service="gdrive", action="list", params={"query": "project specs"})
GeeConnect(service="storage", action="upload", params={"path": "/report.pdf"})
GeeConnect(service="email", action="send", params={"to": "team@co.com", "subject": "Update", "body": "..."})

Available Services

Service	Actions	Description
search	web, news	Web and news search
gdrive	list, read, create	Google Drive file operations
storage	list, upload, download	Gee Cloud storage (S3-backed)
email	send, search	Send emails or search your inbox
calendar	list, create	Calendar event management
memory	search, store, recall	Long-term memory across sessions
knowledge	search	Unified search across all knowledge sources
documents	get, search	Indexed document retrieval

Email

The email service works through your connected Gmail account:

• Send — action="send" with to, subject, body (optional: cc, gmail_thread_id for replies)
• Search — action="search" with query (Gmail search syntax) and optional maxResults

For Gee-to-user communication, prefer SendNotification(channel="email"). GeeConnect’s email service is for broader operations — searching your inbox, sending to third parties, or threading into existing conversations.

AssessCapabilityGap

When a Gee hits a wall — a missing tool, skill, API, or credential — this tool provides a structured analysis and recommends a next step based on the Gee’s autonomy level.

AssessCapabilityGap(
    error_type="missing_skill",
    error_message="No skill available for generating PDF reports",
    task_context="User requested a formatted PDF of the weekly digest"
)

Parameters

Parameter	Default	Description
error_message	(required)	What’s missing or what failed
error_type	"capability_gap"	Type of gap: missing_tool, missing_skill, missing_credential, missing_api, or capability_gap
task_context	—	What you were trying to accomplish when you hit the gap

Autonomy-Aware Routing

The tool’s response changes based on the Gee’s autonomy level:

• Supervised — formats a suggestion for the user to act on
• Semi-autonomous — proposes a plan and requests approval
• Autonomous — returns a skill-building plan the Gee can execute immediately using CreateSkill

What It Returns

The analysis includes:

• Gap type and description
• Recommended action (suggest_to_user, build_skill, or request_credential)
• Skill plan — if the gap can be closed by building a skill, includes a plan with the skill name and approach
• Existing alternatives — partial workarounds already available
• Extension instructions — for build_skill actions, step-by-step instructions for self-extension
• History check — whether this same gap has been encountered before, to avoid repeated failed attempts

This tool is a core part of the autonomous self-improvement loop: encounter a gap, assess it, build a skill to close it, and retry.

AskUserQuestion

Present the user with structured questions and predefined options. Useful when a Gee needs to make a decision and wants to give the user clear choices rather than open-ended questions.

AskUserQuestion(questions=[{
    "header": "Deploy",
    "question": "Which environment should I deploy to?",
    "options": [
        {"label": "Staging", "description": "Deploy to staging for testing"},
        {"label": "Production", "description": "Deploy to production"}
    ],
    "multiSelect": false
}])

The options appear as clickable buttons in The Terminal. Multi-select allows choosing more than one option.

How Communication Fits Together

These tools form a communication stack:

1. AskUserQuestion — interactive, in-terminal decisions (synchronous)
2. SendNotification — proactive outbound messaging to the user (asynchronous)
3. GeeConnect — backend service bridge for email, search, storage (infrastructure)
4. AssessCapabilityGap — structured self-diagnosis when blocked (internal)

In autonomous mode, a typical flow might look like: a Gee encounters a missing capability (AssessCapabilityGap), builds a skill to resolve it, completes its task, and notifies you of the result (SendNotification). If it needs your input, it sends an SMS and waits for your reply on the next activation.

Next Steps

• Web & Browser — web fetching, search, and browser automation
• Tools Overview — the complete tool list
• Autonomy — how Gees operate and communicate