Skip to content

Quick Start

Get a project running in under two minutes — no need to read the full docs first. Install, scaffold, and let your AI agent handle the rest.

1. Install

pip install honey-badgeria[all]

Prerequisites: Python 3.9+ — and Node.js 18+ if using frontend features.

2. Create a Project

hbia init my_api --framework fastapi
cd my_api

Creates a FastAPI project with HBIA graph execution, including flows/, vertices/, tests/, an AGENTS.md context file, and a ready-to-run manage.py.

hbia init my_app --framework monorepo
cd my_app

Creates a full-stack project: back/ (FastAPI + HBIA) and front/ (Next.js + HBIA reactive graphs).

hbia init my_project
cd my_project

Creates a minimal backend project — flows, vertices, and tests. No web framework.

3. Start Prompting

Open the project in your editor with your AI coding agent (Copilot, Cursor, Cline, Windsurf, etc.) and tell it:

"Following the HBIA principles in the AGENTS.md file, build me [describe your app]."

That's it. The project already contains an AGENTS.md file — a complete reference that tells the AI how to structure code, which CLI commands to run, and how to validate its own work.

You don't need to learn the framework

The AGENTS.md file is designed for AI agents, not humans. Your job is to describe what you want; the AI handles the how. If you're curious about what's happening under the hood, the rest of this tutorial walks through every concept in detail.

What Just Happened?

When you ran hbia init, HBIA scaffolded a project with:

  • flows/ — YAML files that define your application architecture as a directed acyclic graph.
  • vertices/ — Python functions that implement each operation in the graph.
  • tests/ — Test files using HBIA's testing framework.
  • AGENTS.md — The AI context file. This is what makes AI-assisted development work — it contains every rule, convention, and reference the agent needs.
  • settings.py — Runtime configuration (caching, parallelism, async).
  • manage.py — Entry point to run flows directly.

The AI agent reads AGENTS.md first, then navigates flows/ to understand the architecture, then writes or modifies vertices/ to implement behavior. The CLI (hbia lint, hbia validate, hbia run) keeps everything in check.

Next Steps