Chat vs Create Modes

Glyph AI supports two conversation modes: Chat and Create. Each mode offers different capabilities and use cases.

Mode Overview

Chat Mode

What is Chat Mode?

Chat mode provides direct conversational interaction with the AI model without any tool access.

Characteristics

• Pure conversation: No file system access
• Faster responses: No tool call overhead
• Simpler interactions: Straightforward Q&A
• Context-only: Can only reference attached context

When to Use Chat Mode

Example Use Cases

❓ User: What are the benefits of the Zettelkasten method?
🤖 AI: [Direct response without searching files]

❓ User: Help me brainstorm blog post topics about productivity.
🤖 AI: [Generates ideas conversationally]

❓ User: Explain the concept of atomic notes.
🤖 AI: [Provides explanation from training data]

Create Mode (Default)

What is Create Mode?

Create mode gives the AI access to workspace tools, allowing it to read files, search notes, and explore your space.

Characteristics

• Tool access: File reading, searching, and listing
• Autonomous exploration: AI decides when to use tools
• Evidence-based: Can cite specific files and content
• Tool discipline: Guided to use minimal tool calls
• Timeline view: See which tools were called and when

Available Tools

read_file

Read the contents of a file in your space.

Parameters:

• path - Relative path to file (e.g., notes/2024-01-15.md)

Limits:

• Max file size: 512 KB
• Max characters: 12,000
• UTF-8 text files only

Example:

AI calls: read_file({"path": "projects/glyph/roadmap.md"})
Returns: File contents (truncated if too large)

search_notes

Search for files matching a query using hybrid search (SQLite FTS + similarity).

Parameters:

• query - Search query
• limit - Max results (default 20, max 200)

Returns:

• File paths matching the query
• Ranked by relevance

Example:

AI calls: search_notes({"query": "AI integration", "limit": 10})
Returns: [
  {"path": "notes/ai-setup.md", "score": 0.95},
  {"path": "projects/ai-features.md", "score": 0.87}
]

list_dir

List files and directories in a path.

Parameters:

• path - Directory path (optional, defaults to root)
• recursive - Include subdirectories (optional)
• depth - Max depth for recursive listing (optional)
• limit - Max files to return (default 1000, max 5000)

Returns:

• List of files and directories
• File metadata (size, modified time)

Example:

AI calls: list_dir({"path": "projects", "recursive": false})
Returns: [
  {"name": "glyph", "type": "dir"},
  {"name": "roadmap.md", "type": "file", "size": 2048}
]

When to Use Create Mode

Example Use Cases

❓ User: What's in my roadmap file?
🤖 AI: [Calls read_file("roadmap.md") and summarizes]

❓ User: Find all notes about AI features.
🤖 AI: [Calls search_notes({query: "AI features"}) and lists results]

❓ User: What projects do I have?
🤖 AI: [Calls list_dir({path: "projects"}) and summarizes]

Tool Discipline

To prevent excessive tool usage, Glyph adds this system prompt in create mode:

Tool discipline for this run: use the minimum number of tool calls needed.
Prefer at most 1-2 search/list calls before answering.
If a tool returns usable evidence, stop searching and summarize what you
found with uncertainty notes rather than continuing to explore.

This encourages the AI to:

• Use tools sparingly
• Stop searching once it finds useful information
• Acknowledge uncertainty instead of over-searching

Switching Between Modes

Modes are set per conversation. To change modes:

1. Start a new conversation in the AI panel
2. Mode defaults to Create
3. To use Chat mode, it must be selected when starting the conversation

Mode Selection in Code

From src/components/ai/hooks/useRigChat.ts:

const { job_id: jobId } = await invoke("ai_chat_start", {
  request: {
    profile_id: profileId,
    messages: asAiMessages([...messagesRef.current, userMessage]),
    thread_id: threadId,
    mode: options?.body?.mode ?? "create", // Default: create
    context: options?.body?.context || undefined,
    context_manifest: options?.body?.context_manifest,
    audit: options?.body?.audit ?? true,
  },
});

Tool Timeline

In create mode, the AI panel shows a tool timeline:

• 🔧 Tool called: Which tool, with what arguments
• ⏱️ Timestamp: When the tool was called
• ✅ Result: Success or error
• 📊 Payload: Tool arguments and response

This provides transparency into how the AI is exploring your workspace.

Performance Considerations

Chat Mode Performance

• ⚡ Fast responses (no tool overhead)
• 💰 Lower token usage (no tool definitions in prompt)
• 🔄 Immediate streaming starts

Create Mode Performance

• 🔧 Tool call latency (AI must decide when to call tools)
• 📈 Higher token usage (tool definitions + results)
• ⏱️ Longer responses (tool execution time)
• 🧠 More thoughtful (AI considers available tools)

Security and Safety

Both modes enforce security restrictions:

Path Safety

• ✅ All paths restricted to current space
• ❌ Path traversal prevented (../ not allowed)
• ❌ Hidden files blocked (files starting with .)
• ❌ Symlinks outside space blocked

File Limits

• Max file read: 512 KB
• Max characters per file: 12,000
• Max search results: 200
• Max directory list: 5,000 files

Audit Trail

Create mode logs all tool usage:

• Stored in .glyph/ai_history/<thread_id>.json
• Includes tool name, arguments, results, timestamps
• Reviewable for compliance and debugging

Best Practices

Use Chat Mode For:

• General knowledge questions
• Creative tasks (writing, brainstorming)
• Conversations that don’t require file access
• When you need fast responses

Use Create Mode For:

• Questions about your specific notes
• Research requiring file exploration
• Summarization of workspace content
• When you need evidence from your files

Combine with Context Attachment

Even in chat mode, you can attach context:

• Attach files or folders manually
• Use @mentions to reference files
• Context sent in system message
• AI can reference without tool calls

Troubleshooting

Tools not being called in create mode

Possible causes:

• Model doesn’t support function calling well (try GPT-4, Claude, or Gemini)
• Question is answerable from training data
• Tool discipline prompt limiting tool usage

Solution: Ask more specific questions that clearly require file access.

Tool calls failing

Possible causes:

• File doesn’t exist
• File is too large (>512 KB)
• File is binary (not UTF-8 text)
• Path contains hidden directories

Solution: Check tool error messages in the timeline view.

Too many tool calls

Cause: AI is exploring extensively before answering.

Solution:

• Make questions more specific
• Attach context manually to reduce exploration
• Use chat mode if file access isn’t needed

Next Steps