Skip to main content
CodeFire can sync your Gmail inbox and automatically create tasks from specific senders. This guide walks through setting up the Gmail integration.

​
Overview

The Gmail integration:
  • Syncs emails from whitelisted senders
  • Automatically creates tasks from email subjects and bodies
  • Links tasks to specific clients (optional)
  • Supports priority flags for urgent emails
  • Polls at configurable intervals (default: every 5 minutes)

​
Prerequisites

You need a Google Cloud Console project with Gmail API access to generate OAuth credentials.
1
Create Google Cloud Project
2
  • Go to Google Cloud Console
  • Create a new project (or select an existing one)
  • Navigate to APIs & Services → Library
  • Search for “Gmail API” and click Enable
    • 3
    Create OAuth Credentials
    4
  • Go to APIs & Services → Credentials
  • Click Create Credentials → OAuth client ID
  • Configure the consent screen:
    • User type: External
    • App name: CodeFire
    • Add your email as a test user
  • Application type: Desktop app
  • Name: CodeFire Gmail Integration
  • Click Create
    • 5
    Copy Client ID and Secret
    6
    After creating the OAuth client, you’ll see a dialog with:
    7
  • Client ID (e.g., 1234567890-abc123.apps.googleusercontent.com)
  • Client Secret (e.g., GOCSPX-abc123xyz)
    • 8
    Keep these safe! You’ll need them in the next step.
    9
    Configure CodeFire
    10
  • Open CodeFire → Settings (Cmd+,)
  • Go to the Gmail tab
  • Paste your Client ID in the first field
  • Paste your Client Secret in the second field
  • Click Add Gmail Account
  • Complete the OAuth flow in your browser
  • Grant CodeFire permission to read your Gmail
    • 11
    Enable Sync
    12
  • In the Gmail settings tab, toggle Enable Gmail sync
  • Adjust the sync interval (default: 5 minutes)
  • CodeFire will now poll for new emails at the specified interval

    • ​
    Whitelist Rules

    CodeFire only creates tasks from whitelisted senders. This prevents spam and irrelevant emails from cluttering your task board.

    ​
    Adding a Whitelist Rule

    1. Go to Settings → Gmail → Whitelist Rules
    2. Enter a pattern:
      • Full email: [email protected]
      • Domain wildcard: @example.com (matches all senders from that domain)
    3. (Optional) Assign to a Client — tasks from this sender will be linked to the selected client
    4. (Optional) Mark as Priority — tasks will be created with high priority
    5. Click Add

    ​
    Example Rules

    PatternClientPriorityEffect
    @acme.comAcme CorpYesAll emails from acme.com → high-priority tasks linked to Acme Corp
    [email protected]Example IncNoOnly support emails → tasks linked to Example Inc
    @contractor.ioNoneNoAll emails from contractor.io → general tasks (no client)

    ​
    Deleting Rules

    Click the X icon next to any rule to remove it. Deleting a rule does not delete existing tasks.

    ​
    How Auto-Task Creation Works

    1. Poll Gmail — CodeFire checks for new emails at the configured interval
    2. Filter by whitelist — Only emails matching a whitelist rule are processed
    3. Extract task data — Subject becomes task title, body becomes description
    4. Create task — A new task is added to the “Todo” column in the global planner
    5. Store metadata — Task stores Gmail message ID, thread ID, sender, and timestamp
    6. Mark as synced — Email is tracked to avoid duplicate tasks

    ​
    Task Fields from Email

    • Title — Email subject
    • Description — Plain-text email body (HTML is stripped)
    • Client — Matched from whitelist rule (if configured)
    • Priority — Set to 1 (high) if whitelist rule has priority flag
    • Created At — Email received timestamp
    • Labels — Automatically tagged with “email”

    ​
    Skipped Emails

    CodeFire ignores:
    • Calendar invites (detected by MIME type)
    • Emails older than 7 days (configurable via database)
    • Emails from non-whitelisted senders
    • Emails already synced (tracked by message ID)

    ​
    Managing Synced Tasks

    Tasks created from Gmail are regular CodeFire tasks. You can:
    • Edit title, description, priority, labels
    • Move between columns (Todo → In Progress → Done)
    • Delete tasks (does not delete the original email)
    • Link to other tasks or notes

    ​
    Viewing Email Source

    (Future feature) — Click a task to see the original email content, sender, and thread.

    ​
    Sync Settings

    ​
    Sync Interval

    Adjust how often CodeFire checks for new emails:
    • 1 minute (for high-frequency monitoring)
    • 5 minutes (default, balanced)
    • 30 minutes (low-frequency, reduces API quota usage)
    Note: Google’s Gmail API has quota limits. If you exceed them, increase the sync interval.

    ​
    Disable Sync

    Toggle Enable Gmail sync off to pause polling. CodeFire will stop checking for new emails, but existing tasks remain.

    ​
    Troubleshooting

    ​
    OAuth Flow Fails

    Symptom: Browser shows “Access blocked” or “This app isn’t verified” Solution:
    1. Go to Google Cloud Console → OAuth consent screen
    2. Add your email as a Test User
    3. Retry the OAuth flow
    4. Click Advanced → Go to CodeFire (unsafe) if prompted

    ​
    No Tasks Created

    Symptom: Gmail sync is enabled but no tasks appear Solution:
    1. Check Settings → Gmail → Whitelist Rules — at least one rule must exist
    2. Verify incoming emails match a whitelist pattern
    3. Check Settings → Gmail → Connected Accounts — account should show “Active” (green dot)
    4. Check the last sync timestamp — if it’s stale, click Refresh

    ​
    Duplicate Tasks

    Symptom: Same email creates multiple tasks Solution:
    1. This shouldn’t happen (CodeFire tracks message IDs to avoid duplicates)
    2. If it does, check for conflicting whitelist rules
    3. Report the issue on GitHub

    ​
    API Quota Exceeded

    Symptom: Sync stops working, logs show “quota exceeded” Solution:
    1. Increase sync interval to reduce API calls (e.g., 30 minutes)
    2. Check Google Cloud Console → APIs & Services → Dashboard for quota limits
    3. Request a quota increase if needed (for production use)

    ​
    Security & Privacy

    CodeFire stores OAuth tokens securely in macOS Keychain. The tokens grant read-only access to your Gmail. CodeFire cannot:
    • Send emails on your behalf (unless you explicitly use the reply feature)
    • Delete emails
    • Modify Gmail settings
    • Access other Google services
    All email data is stored locally in ~/Library/Application Support/CodeFire/codefire.db. Nothing is sent to external servers.

    ​
    Next Steps

    CLI Integration

    Connect your AI coding CLI

    Workflows

    Common workflows and best practices

    Build docs developers (and LLMs) love

    Get started for freeTalk to us