Skip to content

dikkadev/bangs

BranchesTags

Repository files navigation

Bangs

A lightweight and extensible search engine that leverages "bangs" to quickly redirect queries to your favorite services. Includes a web UI for browsing and searching available bangs. Customize your search experience by defining your own bangs and effortlessly expand its capabilities.

Features

  • Web UI: Browse, filter, and search available bangs through a modern web interface.
  • MCP Server: Model Context Protocol server for AI assistants like Claude to access search functionality.
  • Customizable Bangs: Define and manage your own bangs through a simple bangs.yaml configuration file.
  • Flexible Query Handling: Perform searches using the /bang?q=... endpoint.
  • Flexible Default Search: Specify a default as a URL, single bang, or multi-bang combination (e.g., g+gh opens both Google and GitHub).
  • Multi-Bang Support: Use + to combine bangs (e.g., !g+gh+so query opens Google, GitHub, and StackOverflow).
  • Public Instances: Accessible via https://s.dikka.dev and https://s.dikka.dev with HTTPS support (serving the web UI and handling bang redirects).
  • Extensible & Open: Contributions to expand and refine bang definitions are highly encouraged.
  • Robust Testing: Automated Go workflows ensure the correctness and reliability of bang URLs.
  • Categorized Bangs: Organize bangs into categories for better management and user experience.

Public Instances

Experience Bangs, including the web UI, without any setup by using our public instance:

The URL serves the web UI at the root, handles bang redirection via /bang, and supports HTTPS for secure connections.

Installation

Docker (Preferred)

The Docker image includes the pre-built web UI and the Go backend.

  • Docker Image: Hosted on GitHub Container Registry (ghcr.io).

  • Usage:

    docker run -d -p 8080:8080 -v ./bangs.yaml:/app/bangs.yaml -e BANGS_BANGFILE=/app/bangs.yaml ghcr.io/dikkadev/bangs:latest

    Or use with Docker Compose:

    services:
  bangs:
    image: ghcr.io/dikkadev/bangs:latest
    restart: unless-stopped
    pull_policy: always
    ports:
      - 8080:8080
    volumes:
      - ./bangs.yaml:/app/bangs.yaml # Mount your bangs config
    environment:
      - BANGS_BANGFILE=/app/bangs.yaml
      - BANGS_WATCH=true # Optional: Reload bangs.yaml on change
      # Add other BANGS_* environment variables as needed (see Command-Line Options below)

Build from Source

Ensure you have Go (version 1.21 or later) and Bun installed.

  1. Clone the Repository

    git clone https://github.com/dikkadev/bangs.git
cd bangs

  2. Build the Frontend

    cd frontend
bun install
bun run build
cd .. # Go back to the root directory

  3. Build the Go Application

    go build -o bangs .

Usage

  1. Start the Application:

    • If built from source: ./bangs -b path/to/your/bangs.yaml
    • If using Docker: Use docker run or docker compose up as shown in Installation.

  2. Access the Web UI: Open your browser to http://localhost:PORT (e.g., http://localhost:8080). Here you can browse, search, and filter available bangs.

  3. Perform Bang Redirects: Use the /bang endpoint with the q query parameter.

    Example (GitHub Search):

    http://localhost:8080/bang?q=!gh dikkadev/bangs

    Explanation: The above URL uses the !gh bang to perform a GitHub search for the repository dikkadev/bangs.

    Example (Default Search):

    If a default URL is defined in bangs.yaml, queries to /bang?q=... without a recognized bang prefix will use the default search engine.

    http://localhost:8080/bang?q=OpenAI ChatGPT

    Example (Double Hashtag Search):

    Prefixing the query with ## also forces the use of the default search engine.

    http://localhost:8080/bang?q=##OpenAI ChatGPT

  4. API Endpoint: The frontend uses the /api/list endpoint to fetch the available bangs data in JSON format.

Command-Line Options & Environment Variables

The application can be configured via command-line flags or corresponding environment variables.

Flag Env Variable Description Default Example
--bangs BANGS_BANGFILE Path to the YAML file containing bang definitions. (Required) -b bangs.yaml
--port BANGS_PORT Port on which the server will run. 8080 -p 9090
--watch BANGS_WATCH Reload bangs file on change. false -w
--allow-no-bang BANGS_ALLOW_NO_BANG Allow /bang requests with no bang to be handled by default. false -a
--ignore-char BANGS_IGNORE_CHAR Start /bang query with this char to ignore bangs. . -i ~
--verbose BANGS_VERBOSE Enable verbose debug logging. false -v
--help Show help message. false -h

Note: Environment variables take precedence over default values, and command-line flags take precedence over environment variables.

Configuration (bangs.yaml)

Bangs are defined in a bangs.yaml file. Each bang maps a unique name (used internally and in the UI) to its properties: bang characters, search url (with {} placeholder), description, and optional category.

The default key at the root specifies what happens for queries without a bang. This can be a URL, a single bang reference, or multiple bang references.

Example bangs.yaml:

# URL default:
# default: 'https://www.google.com/search?q={}'

# Single bang reference as default:
# default: 'g'

# Multi-bang reference as default (opens multiple tabs):
default: 'g+gh'

# Other examples:
# default: 'ai+g'        # AI search + Google  
# default: 'g+gh+so'     # Google + GitHub + StackOverflow
# default: 'ddg'         # Just DuckDuckGo

# Bang Definitions (Key is the name)
GitHub:
  bang: 'gh'
  url: 'https://github.com/search?q={}'
  description: 'Search code repositories on GitHub'
  category: 'Development'

Google:
  bang: "g"
  url: "https://www.google.com/search?q={}"
  description: 'Popular global search engine by Google.'
  category: 'Search'

ChatGPT:
  bang: "ai"
  url: "https://chatgpt.com/?q={}"
  description: 'AI assistant for questions and tasks'
  category: 'AI'

Aliases

Aliases allow you to create custom shortcuts for single bangs or multi-bang combinations. They are defined in the aliases section of your bangs.yaml file.

Example with aliases:

# Aliases - Custom shortcuts for bangs
aliases:
  def: 'ai+g'        # !def -> AI search + Google
  search: 'g'        # !search -> Google only  
  shop: 'a+eb'       # !shop -> Amazon + eBay

# Regular bang definitions...
Google:
  bang: "g"
  url: "https://www.google.com/search?q={}"
  description: 'Popular global search engine'
  category: 'Search'

Amazon:
  bang: "a"
  url: "https://www.amazon.com/s?k={}"
  description: 'E-commerce platform'
  category: 'Shopping'

Usage examples:

  • !def machine learning → Opens both ChatGPT and Google with "machine learning"
  • !search python → Opens Google with "python"
  • !shop laptop → Opens both Amazon and eBay with "laptop"

Aliases are displayed in the web UI with a special "Aliases" category and purple styling to distinguish them from regular bangs.

Default Configuration Options

  • URL: default: 'https://www.google.com/search?q={}' - URL with {} placeholder
  • Single Bang: default: 'g' - Uses the Google bang for all default searches
  • Multi-Bang: default: 'g+gh' - Opens both Google and GitHub in separate tabs
  • Complex Multi-Bang: default: 'ai+g+so' - Opens AI, Google, and StackOverflow

MCP Server (Model Context Protocol)

Bangs includes a separate MCP server that provides AI assistants like Claude with access to search functionality through the Model Context Protocol. This allows LLMs to discover available search engines and execute searches programmatically.

Features

  • Tools: Execute single or multi-bang searches, get bangs by category
  • Resources: Browse complete bang registry and available categories
  • Dual Transport: Supports both stdio and HTTP modes
  • Hot Reload: Automatically reloads when bangs.yaml changes
  • No Installation Required: Run directly with go run command

Quick Start

  1. Download Configuration:

    curl -o ~/bangs.yaml https://raw.githubusercontent.com/dikkadev/bangs/main/bangs.yaml

  2. Run MCP Server:

    go run github.com/dikkadev/bangs/mcp@latest -b ~/bangs.yaml

MCP Client Configuration

Claude Desktop (Local)

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "bangs": {
      "command": ["go", "run", "github.com/dikkadev/bangs/mcp@latest"],
      "args": ["-b", "~/bangs.yaml"],
      "env": {
        "BANGS_WATCH": "true",
        "BANGS_VERBOSE": "false"
      }
    }
  }
}

opencode (Local)

Add to your opencode.json configuration:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "bangs": {
      "type": "local",
      "command": ["go", "run", "github.com/dikkadev/bangs/mcp@latest"],
      "args": ["-b", "~/bangs.yaml"],
      "enabled": true,
      "environment": {
        "BANGS_WATCH": "true"
      }
    }
  }
}

Remote MCP Server

For HTTP-based MCP clients, you can run the server in HTTP mode:

go run github.com/dikkadev/bangs/mcp@latest -b ~/bangs.yaml --http --port 8081

Then configure your MCP client:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "bangs-remote": {
      "type": "remote",
      "url": "http://localhost:8081/mcp",
      "enabled": true
    }
  }
}

Docker Deployment

The MCP server is included in the Docker image and can be run alongside the web server:

# docker-compose.yml
services:
  bangs:
    image: ghcr.io/dikkadev/bangs:latest
    ports: ["8080:8080"]
    volumes: ["./bangs.yaml:/app/bangs.yaml"]
    environment:
      - BANGS_BANGFILE=/app/bangs.yaml

  bangs-mcp:
    image: ghcr.io/dikkadev/bangs:latest
    entrypoint: ["/app/bangs-mcp"]
    ports: ["8081:8081"]
    volumes: ["./bangs.yaml:/app/bangs.yaml"]
    environment:
      - BANGS_BANGFILE=/app/bangs.yaml
      - BANGS_MCP_HTTP=true
      - BANGS_MCP_PORT=8081
      - BANGS_WATCH=true
    profiles: ["mcp"]  # Optional, disabled by default

Usage:

# Run both web and MCP servers
docker compose --profile mcp up

# Run only MCP server
docker compose --profile mcp up bangs-mcp

Available Tools

The MCP server provides these tools to AI assistants:

execute_bang

Execute a search using a specific bang.

  • Parameters: bang (string), query (string)
  • Example: execute_bang(bang="gh", query="golang mcp")
  • Returns: Generated search URL

execute_multi_bang

Execute a search using multiple bangs simultaneously.

  • Parameters: bangs (array), query (string)
  • Example: execute_multi_bang(bangs=["gh", "g"], query="golang mcp")
  • Returns: Multiple URLs with error handling for invalid bangs

get_bangs_by_category

Get all bangs in a specific category.

  • Parameters: category (string)
  • Example: get_bangs_by_category(category="Development")
  • Returns: List of bangs in the specified category

Available Resources

bangs://registry

Complete bang registry with all available search engines, their descriptions, categories, and URL templates.

bangs://categories

List of all available categories for organizing and filtering bangs.

Command-Line Options

Flag Env Variable Description Default Example
--bangs BANGS_BANGFILE Path to bangs.yaml file Required -b ~/bangs.yaml
--http BANGS_MCP_HTTP Run in HTTP mode false --http
--port BANGS_MCP_PORT HTTP server port 8081 -p 8082
--watch BANGS_WATCH Reload config on changes false -w
--verbose BANGS_VERBOSE Enable debug logging false -v

Example AI Interactions

Once configured, AI assistants can use bangs like this:

User: "Search for Go MCP libraries on GitHub and Google"
AI: Uses execute_multi_bang tool with bangs=["gh", "g"] and query="Go MCP libraries"

User: "What development tools are available?"
AI: Uses get_bangs_by_category tool with category="Development"

User: "Find the latest React documentation"
AI: Uses execute_bang tool with bang="mdn" and query="React documentation"

Setting Bangs as the Default Search Engine

You can configure your browser to use your running Bangs instance (local or public) as the default search engine. The exact method varies by browser, but generally involves setting the search URL to:

http://YOUR_INSTANCE_URL/bang?q=%s

Replace YOUR_INSTANCE_URL with the appropriate address (e.g., localhost:8080, s.dikka.dev).

Chromium-Based Browsers

Search for adding a custom search engine in your browser's settings.

Firefox

Requires an extension like "Add custom search engine".

Pop-up / Redirect Settings

Multiple bangs (e.g., chaining multiple bangs in one query) open separate tabs or pop-up windows by design, which may be blocked by default. To ensure multibangs work as expected, allow pop-ups/redirects for your Bangs instance domain (e.g., https://s.dikka.dev) in your browser settings. Refer to your browser’s documentation for instructions on enabling pop-ups or redirects if needed.

Advanced Usage

For details on advanced configurations and persistent setups, please refer to the Advanced Usage guide.

License

LICENSE

Happy Searching! 🚀

About

Search any service with customizable !bang shortcuts & web UI

s.dikka.dev

Topics

search service

Resources

Readme

License

Unlicense license
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

39 tags

Packages

 
 
 

Contributors 4

  •  
  •  
  •  
  •  

Languages