Frequently asked questions

Humbug is an extensible, open-source tool designed for AI-first software development. It provides an integrated environment that helps you develop and support software throughout its lifecycle with AI assistance.

Unlike AI code completion tools or AI app builders, Humbug is built to help you maintain and evolve your software over time, not just speed up editing or create the initial version.

Tools like Cursor, Windsurf, GitHub Copilot, etc., focus on coding and usually exist within existing IDEs and editors. Humbug is designed with a different purpose.

Humbug is designed with the idea that people and AI assistants need to have a shared view of the problems you're trying to solve, how your software should solve them, and how AIs can give you the best help.

Key to this:

• It provides a shared "mindspace" for human and AI collaborative work
• It integrates the Metaphor language to help structure complex tasks
• It provides a multi-AI interaction environment where you can work with multiple models simultaneously
• It's designed to capture and maintain context throughout the software lifecycle
• It focuses on the full development process, not just coding

Humbug can work alongside your existing development environment, but in working with AI assistants you'll find yourself spending less time needing to use them.

Humbug supports AI models from multiple providers including:

• Anthropic (Claude models)
• DeepSeek
• Google (Gemini models)
• Mistral
• Ollama
• OpenAI (GPT models)
• xAI (Grok models)

This allows you to choose the best model for your specific needs, or use different models for different aspects of your projects.

You can use either local or cloud-hosted AIs.

Yes, Humbug is open-source and free to download and use. The software itself doesn't have any usage fees. However, when using commercial AI models (like those from Anthropic, OpenAI, etc.), you will need to use your own API keys and pay for any usage according to those providers' pricing models.

Humbug also works with local models such as Ollama, which can be used without API costs. It also works with private LLM instances if you have them available locally or in the cloud.

To get started, Google and Mistral currently offer a free tier of API access. You can find out more about this and how to get started with our Getting started with Metaphor guide.

Humbug is cross-platform and runs on:

• MacOS
• Windows
• Linux

While Humbug has some elements that are often found in an IDE its main focus is supporting a shared dialog between a people and AIs. It's designed to visualise many different aspects of software development, and it's designed to help with the needs of product managers, designers, architects, security analysts, etc., not just developers.

The rise of agentic coding will definitely reduce the need for human engineers to spend as much time in IDEs and editors, but Humbug isn't designed as an IDE. It's designed to help humans and AIs have high quality conversations about what you want to build.

The best way to visualize all that content is through a graphical front end.

Humbug was the name of the v5.1 ROM monitor software on the first computer Dave used in 1979.

As an open-source project, Humbug welcomes contributions! You can contribute by:

• Submitting pull requests on GitHub
• Reporting bugs or suggesting features through issues
• Improving documentation
• Sharing your experiences and use cases in the community

Visit the Humbug GitHub repository to get started.

Metaphor is an easy-to-learn, open-source, prompt creation language designed to help capture software requirements, design decisions, and context in a structured way that AI can use to help build and maintain software.

It allows you to describe what you want your software to do, rather than focusing on implementation details, and can incorporate knowledge from across your team to create comprehensive requirements that AI can work with.

Unlike ad-hoc prompts, Metaphor provides a structured approach with several advantages:

• A consistent format that can be shared, versioned, and reused
• The ability to modularize and compose Metaphor files by using the Include: keyword
• Providing files as context to a prompt by using the Embed: keyword
• Integration with development workflows and version control
• A focus on capturing the "what" and "why" of software, not just the "how"

This structured approach helps reduce ambiguity and makes it easier to maintain and evolve software over time.

No, Metaphor is intentionally simple and primarily uses natural language. It has only a few keywords (Role:, Context:, Action:, Include:, and Embed:) to structure your content, but the majority of what you write is in plain English (or your preferred language).

Metaphor is designed to be accessible to everyone on a product team, not just developers. Product managers, designers, QA analysts, and other stakeholders can all contribute to Metaphor descriptions.

Ad-hoc prompting of AIs can give very mixed results. We wanted to make prompting follow the best practices from software development - putting the engineering into "prompt engineering".

By providing fine-grained control over files embedded into prompts we could also make it easy to ensure context blocks could include commentary on why a file was being embedded. This takes away guesswork for you AI. Having the ability to break prompts into reusable components follows many decaded of good software design practices by allowing you to have one golden reference, and not have to worry about having dozens of slightly different versions of the same things.

Yes, Metaphor is designed let you capture just the context you need to solve your problem. You can describe what you need the AI to do, and give it the files it needs to do the work, but you don't need to give it your whole codebase.

This helps keep your context small enough to get great results from an LLM and also helps you keep any token usage costs under tight control.

Yes, Metaphor is available as a standalone library (m6rclib) and command-line tool (m6rc) that you can use independently of Humbug. These tools allow you to compile Metaphor descriptions into prompts that can be used with any AI service.

You can find these tools at github.com/m6r-ai/m6rclib and github.com/m6r-ai/m6rc.

Yes, we use Metaphor and Humbug to build and maintain all our software. That's Metaphor and Humbug themselves, but also a host of other tools, and even the M6R website you're now reading.

We've also worked closely with development teams who want to try this for themselves, and we've seen the same successes repeated each time.

One of the more surprising things you can do with Metaphor (and Humbug) is structure a conversation about a different conversation. Humbug captures conversations with AIs as JSON files, so it's easy to embed them in a Metaphor prompt.

This means you can do things like discuss a design with one AI and then ask a second one to comment on it, summarise was was discovered, or ask it for ideas on how to resolve any problems that emerged.

Metaphor files (.m6r) are plain text files that can be stored in your existing version control system (like Git). This allows you to:

• Track changes to requirements over time
• Use branch-based workflows for new features
• Perform code reviews on requirement changes
• Collaborate across teams using familiar tools

The modular nature of Metaphor (with the Include: keyword) also supports breaking down large projects into manageable components that different teams can work on.

You can find tutorials and examples at:

• Getting started with Metaphor
• Hello Metaphor tutorial
• commit-critic example
• Blog editor example
• Code review example

You can also check our YouTube channel for video tutorials and demonstrations.