Skip to main content

​
System Requirements

Operating System

macOS 14.0 (Sonoma) or later

Architecture

Intel or Apple Silicon (Universal Binary)

​
Required Software

​
Optional Software

  • GitHub CLI (gh) — For GitHub integration features
  • OpenRouter API key — For AI-powered features (chat, semantic search, image generation)

​
Download

Get the latest version of CodeFire from the official GitHub repository: Download CodeFire.app
CodeFire is distributed as a universal macOS app bundle that works on both Intel and Apple Silicon Macs.

​
Installation Steps

1

Download the App

Download CodeFire.app from the latest GitHub release.
2

Move to Applications

Drag CodeFire.app to your /Applications folder.
# Or use the command line:
mv ~/Downloads/CodeFire.app /Applications/
3

First Launch

Open CodeFire from your Applications folder.
On first launch, macOS Gatekeeper may block the app because it’s not signed with an Apple Developer certificate. To open it:
  1. Right-click on CodeFire.app
  2. Select Open
  3. Click Open in the security dialog
Alternatively, go to System Settings → Privacy & Security and click Open Anyway.
4

Verify Installation

On successful launch, CodeFire will:
  • Create its data directory at ~/Library/Application Support/CodeFire/
  • Initialize the SQLite database (codefire.db)
  • Install the MCP server binary to ~/Library/Application Support/CodeFire/bin/CodeFireMCP
  • Auto-discover any existing projects in ~/.claude/projects/

​
MCP Server Installation

The MCP server enables your AI coding agent to interact with CodeFire’s project data, tasks, and notes.
1

Open Settings

In CodeFire, press Cmd + , or go to CodeFire → Settings.
2

Navigate to MCP Tab

Click on the MCP Server tab.
3

Select Your CLI Tool

Click the install button for your AI coding tool (Claude Code, Gemini CLI, Codex CLI, or OpenCode).CodeFire will automatically configure the MCP server for that tool.

​
Manual Installation

If you prefer manual configuration or the one-click installer doesn’t work, follow these instructions:
Run this command in your terminal:
claude mcp add codefire ~/Library/Application\ Support/CodeFire/bin/CodeFireMCP
To verify the installation:
claude mcp list
You should see codefire in the list of installed MCP servers.
Edit or create ~/.gemini/settings.json and add:
{
  "mcpServers": {
    "codefire": {
      "command": "~/Library/Application Support/CodeFire/bin/CodeFireMCP",
      "args": []
    }
  }
}
If you already have other MCP servers configured, add the codefire entry to the existing mcpServers object.
Edit or create ~/.codex/config.toml and add:
[mcp_servers.codefire]
command = "~/Library/Application Support/CodeFire/bin/CodeFireMCP"
args = []
Edit or create ~/.opencode/config.json and add:
{
  "mcpServers": {
    "codefire": {
      "command": "~/Library/Application Support/CodeFire/bin/CodeFireMCP",
      "args": []
    }
  }
}
If you already have other MCP servers configured, add the codefire entry to the existing mcpServers object.

​
Optional Integrations

​
OpenRouter API Key

Required for AI-powered features (chat, semantic search, image generation):
1

Get an API Key

Visit OpenRouter and create an account if you don’t have one.Generate a new API key.
2

Add to CodeFire

  1. Open CodeFire Settings (Cmd + ,)
  2. Navigate to the CodeFire Engine tab
  3. Paste your API key in the field
  4. Click Save

​
GitHub CLI Setup

Enables GitHub integration (PRs, issues, CI status, commits): 
# Install GitHub CLI
brew install gh

# Authenticate
gh auth login
Once installed and authenticated, CodeFire will automatically detect gh and enable GitHub features.

​
Gmail OAuth Setup

Enables email-to-task sync and Gmail integration:
1

Create OAuth Credentials

  1. Go to Google Cloud Console
  2. Create a new project or select an existing one
  3. Navigate to APIs & Services → Credentials
  4. Click Create Credentials → OAuth 2.0 Client ID
  5. Configure the OAuth consent screen if prompted
  6. Select Desktop app as the application type
  7. Copy the Client ID and Client Secret
2

Configure in CodeFire

  1. Open CodeFire Settings (Cmd + ,)
  2. Navigate to the Gmail tab
  3. Paste your Client ID and Client Secret
  4. Click Authenticate
  5. Follow the OAuth flow in your browser

​
Building from Source

If you prefer to build CodeFire yourself: 
# Clone the repository
git clone https://github.com/websitebutlers/codefire-app.git
cd codefire-app

# Build and package
bash scripts/package-app.sh

# Copy to Applications
cp -r build/CodeFire.app /Applications/
CodeFire uses Swift Package Manager exclusively. No Xcode project is required, though you can open Package.swift in Xcode if preferred.

​
Troubleshooting

Symptom: macOS blocks CodeFire from opening with a security warning.Solution:
  1. Right-click on CodeFire.app in Applications
  2. Select Open
  3. Click Open in the dialog
Or use System Settings:
  1. Go to System Settings → Privacy & Security
  2. Scroll to the Security section
  3. Click Open Anyway next to the CodeFire warning
Symptom: AI agent doesn’t see CodeFire tools or can’t list tasks.Solution:
  1. Verify the MCP server binary exists: 
    ls -l ~/Library/Application\ Support/CodeFire/bin/CodeFireMCP
  2. Check file permissions: 
    chmod +x ~/Library/Application\ Support/CodeFire/bin/CodeFireMCP
  3. Test the MCP server manually: 
    ~/Library/Application\ Support/CodeFire/bin/CodeFireMCP
    Press Ctrl+D to exit.
  4. Restart your AI CLI tool after configuration changes.
Symptom: CodeFire doesn’t show your Claude Code projects.Solution:
  1. Verify your projects exist in ~/.claude/projects/: 
    ls ~/.claude/projects/
  2. Click the Refresh button in CodeFire’s sidebar
  3. Manually add a project using the + button
Symptom: CodeFire crashes on launch or shows database errors.Solution:
  1. Backup your data: 
    cp ~/Library/Application\ Support/CodeFire/codefire.db ~/Desktop/codefire-backup.db
  2. Reset the database: 
    rm ~/Library/Application\ Support/CodeFire/codefire.db
  3. Relaunch CodeFire (it will create a fresh database)
Symptom: Chat, semantic search, or image generation fail.Solution:
  1. Verify you’ve added an OpenRouter API key in Settings → CodeFire Engine
  2. Check your OpenRouter account has credits/balance
  3. Test the API key: 
    curl https://openrouter.ai/api/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"
Symptom: Built-in terminal shows errors or won’t launch shells.Solution:
  1. Grant Terminal permissions in System Settings → Privacy & Security → Full Disk Access
  2. Add CodeFire to the list if not already present
  3. Restart CodeFire

​
Data Locations

CodeFire stores data in standard macOS locations:
PathContents
~/Library/Application Support/CodeFire/Main data directory
~/Library/Application Support/CodeFire/codefire.dbSQLite database (tasks, notes, sessions)
~/Library/Application Support/CodeFire/bin/CodeFireMCPMCP server binary
~/.claude/projects/Auto-discovered Claude Code projects

​
Uninstallation

To completely remove CodeFire: 
# Remove the app
rm -rf /Applications/CodeFire.app

# Remove data directory
rm -rf ~/Library/Application\ Support/CodeFire

# Remove MCP configuration (Claude Code example)
claude mcp remove codefire
Removing ~/Library/Application Support/CodeFire/ will delete all tasks, notes, and session history.

​
Next Steps

Quick Start

Get up and running in minutes

Features Guide

Explore all CodeFire capabilities

Build docs developers (and LLMs) love

Get started for freeTalk to us