A gift-giving workflow built on top of Poke (by The Interaction Company) that finds deeply personalized gifts through peer-to-peer AI agent collaboration and autonomous message analysis.

TreeHacks 2026 Project

Concierge helps you find the perfect gift by having your Poke agent collaborate with the recipient's Poke agent to discover deeply personalized gift ideas—backed by specific message citations that prove real research.

Generic LLMs give generic gift advice with no proof:

• "Get them a keyboard, they like tech" ❌
• No evidence, no personalization, no confidence

Concierge provides gift recommendations with citation traceability:

• Recommendation: Keychron K8 mechanical keyboard (Navy, $97.19) ✅
• Citation 1 (3 months ago): "I've been really into mechanical keyboards lately"
• Citation 2 (2 months ago): "The clicky sound is so satisfying!"
• Citation 3 (1 month ago): "My wrists hurt from this laptop keyboard"
• Proof: Not generic—deeply researched with specific evidence

An autonomous agent loop validates gift hypotheses by iteratively searching the recipient's message history:

• Tests initial hypothesis
• Finds contradicting evidence
• Updates its own hypothesis
• Continues until confident
• Returns validated ideas with citations

Two Poke agents work together:

• Gift Giver's Poke: Initiates request, receives recommendations
• Gift Recipient's Poke: Orchestrates research, validates hypotheses

Recipient's Poke accesses their complete message history:

• Shared messages (Giver ↔ Recipient): Shared experiences
• Other conversations (Recipient ↔ Others): General interests
• Result: Combined context for better personalization

Browser automation configures products based on message insights:

• Size: Extracted from messages ("I'm a size 10")
• Color: From favorite color mentions
• Variant: From specific preference messages

Web dashboard shows the entire process:

• Agent conversation in real-time
• Autonomous loop iterations
• Hypothesis updates (invalidated → refined → validated)
• Citations as they're discovered
• Final recommendations with evidence

Quick Links:

• 📋 PRD.md - Complete product specification (GROUND TRUTH)
• 🤖 agents.md - Agent architecture and collaboration patterns
• 📚 DOCUMENTATION_INDEX.md - Documentation hub
• ⚡ QUICK_REFERENCE.md - Commands & workflows

The PRD is the ground truth for all development and serves as centralized context for this project.

Person A (Gift Giver)
    ↓ "Buy gift for Person B, $100, tech"
┌─────────────┐
│   Poke A    │
└──────┬──────┘
       │ Poke-to-Poke MCP
       ↓
┌────────────────────────────┐
│   Poke B (Orchestrator)    │
│  - Email receipt analysis  │
│  - Hypothesis generation   │
│  - Orchestrate subagents   │
└──┬─────────────────────┬───┘
   │                     │
   ↓                     ↓
┌──────────────────┐  ┌────────────────┐
│ iMessage Subagent│  │ Browser Agent  │
│ (Autonomous Loop)│  │ (Browserbase)  │
│                  │  │                │
│ - Test hypothesis│  │ - Find product │
│ - Search messages│  │ - Configure    │
│ - Validate/Update│  │ - Get checkout │
│ - Find citations │  │   URL          │
└──────────────────┘  └────────────────┘
   │                     │
   └────────┬────────────┘
            ↓
   3 Gift Recommendations
   + Citations + URLs
            ↓
        Poke A
            ↓
      Person A

Built on: Poke by The Interaction Company
Extension Method: MCP (Model Context Protocol) servers

• Python 3.12+
• Node.js 18+
• uv (Python package manager)
• macOS (for iMessage database access)
• Supabase account
• Browserbase account

1. Install Python dependencies:

uv sync

2. Configure environment variables:

cp env.example .env
# Edit .env with your keys (see env.example for all options):
# - POKE_A_KEY / POKE_B_KEY (agent authentication)
# - SUPABASE credentials
# - BROWSERBASE_API_KEY
# - ANTHROPIC_API_KEY or OPENAI_API_KEY

3. Run the Poke-to-Poke MCP server:

python mcp/poke-to-poke/server.py

treehacks26/
├── mcp/
│   └── poke-to-poke/              # Agent communication MCP server ✅
│       └── server.py
├── agents/                         # Agent logic (to be implemented)
│   ├── poke_b_orchestrator.py     # 🔄 Orchestrates gift research
│   ├── imessage_subagent.py       # 🔄 Autonomous hypothesis validation
│   └── browser_automation.py      # 🔄 Product search & configuration
├── app/                            # Next.js dashboard (to be implemented)
│   ├── page.tsx                   # 🔄 Main dashboard
│   ├── session/[id]/              # 🔄 Gift session view
│   └── components/                # 🔄 React components
├── supabase/                       # Database migrations (to be implemented)
│   └── migrations/                # 🔄 Schema definitions
├── PRD.md                          # 📋 Product requirements (GROUND TRUTH)
├── agents.md                       # 🤖 Agent architecture reference
├── README.md                       # 🚀 This file
├── conversation.txt                # 💬 Agent communication log
├── env.example                     # 🔐 Environment template
├── pyproject.toml                  # Python dependencies
└── package.json                    # 🔄 Node.js dependencies (to be added)

Legend: ✅ Implemented | 🔄 To be implemented

• Project structure and documentation
• Comprehensive PRD (ground truth)
• Poke-to-Poke MCP server (basic implementation)
• Agent authentication system
• Local conversation file storage

• Phase 1: Foundation

  • Next.js app with Supabase integration
  • Update poke-to-poke MCP for Concierge workflow
  • Supabase schema implementation
  • Basic dashboard UI

• Phase 2: iMessage Integration

  • iMessage Query MCP server
  • Structured search tools (search_messages, analyze_sentiment)
  • Message context extraction
  • Test with real iMessage database

• Phase 3: Autonomous Agent

  • iMessage subagent autonomous loop
  • Hypothesis validation logic
  • Stop conditions
  • Citation extraction

• Phase 4: Orchestration

  • Poke B orchestrator
  • Email receipt integration
  • Gift idea synthesis
  • Agent coordination

• Phase 5: Browser Automation

  • Browserbase integration
  • Product search
  • Configuration (size/color)
  • Checkout URL extraction

• Phase 6: Dashboard

  • Real-time conversation viewer
  • Autonomous loop visualizer
  • Citation display cards
  • Gift recommendation cards

• Phase 7: End-to-End

  • Full flow integration
  • Testing with real data
  • Demo preparation

See PRD.md Section 10 for detailed roadmap.

# Start server
python mcp/poke-to-poke/server.py

# Send test message
curl -X POST http://localhost:8000/mcp/v1/tools/call \
  -H "Authorization: Bearer $POKE_A_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "send_message",
      "arguments": {
        "message": "[REQUEST] Test gift request"
      }
    },
    "id": 1
  }'

# Get conversation history
curl -X POST http://localhost:8000/mcp/v1/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_conversation",
      "arguments": {}
    },
    "id": 2
  }'

tail -f conversation.txt

When demonstrating Concierge at TreeHacks:

Show specific messages from months ago:

• Message timestamp: "5 months ago"
• Full context: conversation with other friends
• Proves deep research vs generic LLM

Visualize hypothesis evolution:

• Initial: "Person B likes Warriors"
• Finding: 15 messages about Cavaliers instead
• Updated: "Person B likes Cavaliers" ✅
• Shows real reasoning, not pattern matching

Demonstrate access to full message history:

• Shared experiences: Trip to Japan (from A ↔ B messages)
• General interests: Loves ramen (from B ↔ C messages)
• Combined insight: Japanese cooking class gift

Show attention to detail:

• Found in messages: "I'm a size 10", "Navy blue is my favorite"
• Product configured: Nike shoes, size 10, navy blue
• Not generic recommendation

Dashboard shows entire research process:

• Agent conversation
• Autonomous loop iterations
• Citations appearing
• Products being configured

Compare side-by-side:

• Generic LLM: "Get them a keyboard" (no proof)
• Concierge: "Keychron K8 because [3 specific citations from their messages]" (proven)

# Agent Authentication
POKE_A_KEY=xxx                          # Gift giver's agent
POKE_B_KEY=yyy                          # Gift recipient's agent

# Supabase
NEXT_PUBLIC_SUPABASE_URL=xxx
NEXT_PUBLIC_SUPABASE_ANON_KEY=xxx
SUPABASE_SERVICE_ROLE_KEY=xxx

# LLM (for agent reasoning)
ANTHROPIC_API_KEY=xxx                   # Claude
# or
OPENAI_API_KEY=xxx                      # GPT

# Browser Automation
BROWSERBASE_API_KEY=xxx
BROWSERBASE_PROJECT_ID=xxx

# iMessage Query
IMESSAGE_DB_PATH=~/Library/Messages/chat.db
MAX_IMESSAGE_ITERATIONS=10
RELEVANCE_THRESHOLD=0.7

# Poke Integration
POKE_API_KEY=xxx                        # If Poke provides API access

See env.example for complete list.

• Python 3.12+: Agent logic, MCP servers
• fastmcp 2.14.5+: MCP server framework
• FastAPI: HTTP transport for MCP
• SQLite: iMessage database queries
• Supabase: PostgreSQL for application data

• Next.js 14+: Web dashboard
• React 18+: UI components
• TypeScript: Type safety
• TailwindCSS: Styling
• React Query: Real-time polling

• Supabase: Database, auth, real-time
• Browserbase: Cloud browser automation
• Vercel: Next.js hosting (production)

• Claude (Anthropic) or GPT (OpenAI): Agent reasoning
• Agentic Search: Iterative hypothesis validation (no vector embeddings)

This is a TreeHacks 2026 project. For development:

1. Read the PRD: PRD.md is the ground truth
2. Understand Agents: See agents.md for architecture
3. Follow Roadmap: PRD.md Section 10
4. Update Docs: Keep documentation in sync with implementation

• Poke Documentation
• FastMCP Documentation
• Supabase Documentation
• Next.js Documentation
• Browserbase Documentation

• PRD.md - Complete product requirements
• agents.md - Agent system architecture
• DOCUMENTATION_INDEX.md - Doc navigation
• QUICK_REFERENCE.md - Commands cheat sheet

Always refer to PRD.md for authoritative specifications. If there's a conflict between documents, PRD.md wins.

• iMessage database is read-only
• Messages are NOT stored in Supabase (only citations for gift context)
• Full message access requires user consent (skipped for hackathon demo)

• iMessage subagent runs autonomously (updates its own hypotheses)
• Stop conditions prevent infinite loops
• Always returns best candidate even if not fully validated

• Prioritize impressive visualizations
• Emphasize citation traceability
• Show clear differentiation from generic LLMs
• Have backup data in case of network issues

Concierge uses agentic search (not vector embeddings):

• Agent tests hypothesis → analyzes results → updates hypothesis → repeat
• Example: Test "likes Warriors" → finds "likes Cavaliers" → updates and retests
• More transparent and debuggable than embedding similarity

Model Context Protocol (MCP) extends AI capabilities via tool servers:

• Poke is the base AI assistant
• MCP servers provide specialized tools (iMessage search, browser automation)
• Agents call MCP tools to perform actions
• Similar to function calling but standardized

Traditional search: Query → Results → Done
Autonomous loop: Query → Analyze → Update Query → Re-query → Repeat until stop condition

TreeHacks 2026 Team
Built on top of Poke by The Interaction Company

Status: Active Development
Event: TreeHacks 2026
Last Updated: February 14, 2026

# 1. Clone and install
git clone <repo>
cd treehacks26
uv sync

# 2. Configure
cp env.example .env
# Edit .env with your API keys

# 3. Run MCP server
python mcp/poke-to-poke/server.py

# 4. (Later) Run dashboard
npm run dev

# 5. Watch agents communicate
tail -f conversation.txt

Next Steps: See PRD.md Section 10 for implementation phases.