Working with the AI Assistant

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jaypopat/cf_ai_duet/llms.txt

Use this file to discover all available pages before exploring further.

​

AI Features Overview

• Uses Meta’s Llama 3 8B Instruct model via Cloudflare AI (cf-worker/index.ts:123)
• Maintains conversation context (up to 50 messages per room)
• Can execute commands in a dedicated Cloudflare Sandbox
• Shares state across all users in the room via Durable Objects
• Automatically extracts and runs commands wrapped in <run> tags

​

AI Sidebar

​

Toggling the Sidebar

• ctrl+a - Show/hide the AI sidebar
• Sidebar only appears when window is at least 120 characters wide (internal/ui/model.go:21)

​

Scrolling the AI History

• ctrl+j - Scroll down
• ctrl+k - Scroll up
• Auto-scrolls to your most recent prompt after receiving a response

​

AI Sidebar Layout

• Conversation history with role indicators (user/agent)
• Username for each user message
• Timestamp for messages
• Loading spinner when AI is processing
• Up to 10 recent messages used as context for inference

​

Sending AI Messages

​

AI System Prompt

“You are Duet, a concise pair-programming assistant. You can run commands in a sandbox using <run>command</run> tags. When asked to perform an action, briefly explain what you will do and wrap the exact shell command(s) in <run> tags. Do NOT include predicted output in your response - just provide the explanation and command.”

• Give concise, focused responses
• Automatically execute commands when appropriate
• Avoid verbose explanations

​

AI Command Execution

​

How It Works

1. AI generates response with commands in <run> tags:
   I'll search for all JavaScript files in the project.
   <run>find . -name "*.js" -type f</run>
   
2. Commands are extracted and executed in the sandbox (cf-worker/index.ts:185-208)
3. Output is appended to the AI’s response:
   I'll search for all JavaScript files in the project.
   
   Output (find . -name "*.js" -type f):
   ./src/index.js
   ./src/utils.js
   ./test/app.test.js
   
4. Result is broadcast to all users in the room

​

Command Limitations

• Output is truncated to 500 characters (stdout or stderr)
• 30-second timeout per command
• Runs in an isolated Cloudflare Sandbox (not the shared terminal)
• One sandbox instance per room

​

Direct Sandbox Commands

ls -la /app

​

Sandbox vs Terminal

​

AI Message Format

interface DuetMessage {
  role: "user" | "agent";
  userId?: string;  // Username of sender
  text: string;     // Message content
  ts: number;       // Timestamp
}

​

AI Context & Memory

​

Conversation History

• Each room stores up to 50 messages (internal/ui/model.go:179)
• Last 10 messages are sent as context for each new request (cf-worker/index.ts:163)
• History is shared across all users via Durable Object state
• New users joining see full conversation history (internal/ui/model.go:228-230)

​

Syncing Across Users

• When one user sends an AI message, all users see the response
• Updates are broadcast via “ai_sync” events (internal/ui/model.go:205-208)
• AI sidebar automatically updates for all participants

​

Configuration Requirements

./duet --worker https://duet-cf-worker.example.workers.dev

• ctrl+g shows: “AI not configured (no worker URL)”
• ctrl+r shows: “Sandbox not configured (no worker URL)”

​

Troubleshooting

​

”AI not configured”

​

AI Response Timeout

• Try a simpler/shorter prompt
• Check Cloudflare Worker logs for errors
• Verify the worker URL is accessible

​

Command Execution Fails

• Check the error message in the AI response
• Verify the command syntax is correct
• Note that some system commands may not be available in the sandbox

​

AI Sidebar Too Small

• Increase your terminal window size
• Toggle the sidebar off with ctrl+a if you need more terminal space
• Minimum recommended window: 120x24 characters

​

Best Practices

​

Effective AI Prompts

• Be specific: “Parse this JSON file” → “Show me how to parse JSON with error handling in Node.js”
• One task at a time: AI works best with focused requests
• Use for exploration: Great for finding files, checking syntax, quick references

​

Collaboration

• All users see AI responses - communicate before asking questions that might clutter the conversation
• Use AI for repetitive tasks (finding files, boilerplate code)
• Remember: AI runs in sandbox, not the shared terminal

​

Resource Usage

• AI inference happens on Cloudflare’s edge network
• Sandbox execution is isolated per room
• Room cleanup automatically terminates sandbox and resets AI state (cf-worker/index.ts:244-266)