Foreman

Your AI foreman — books jobs, sends invoices, and chases follow-ups, all over WhatsApp.

Comment

Foreman – Your AI Employee on WhatsApp

Inspiration

Most small service businesses—HVAC technicians, plumbers, electricians, and similar trades—don't use expensive CRM software. Their business runs on WhatsApp, spreadsheets, and the owner's memory. Appointments, invoices, follow-ups, and payments often depend on one person remembering everything.

We wanted to build something closer to an AI employee than a chatbot: something a business owner could message naturally, like:

"Schedule Rahul for Friday at 3 PM, invoice him after the job."

Instead of giving instructions, Foreman completes the work and reports back with what actually happened.

What it does

Foreman is an AI employee that lives on WhatsApp.

Business owners send requests in plain language, and Foreman:

  • Plans the request into structured tasks
  • Looks up customers
  • Generates PDF invoices
  • Sends emails
  • Schedules appointments
  • Creates payment reminders
  • Updates customer history
  • Streams every action to a live dashboard
  • Sends a confirmation back on WhatsApp

Foreman also supports multi-turn conversations, allowing owners to naturally refer to previous customers without repeating context.

How we built it

We used Codex with GPT-5.6 throughout development as an AI pair programmer. It helped us scaffold the project, build backend APIs, generate database models, refactor React components, debug integrations, write tests, and produce documentation, allowing us to focus on architecture and product design.

The deployed application separates planning from execution. The runtime planner currently uses Groq (Llama 3.3 70B) behind a provider-agnostic PlannerLLM interface, making it easy to swap to GPT-5.6 or another compatible model later without changing the rest of the system.

Tech Stack

  • Frontend: Next.js 15, Tailwind CSS, shadcn/ui
  • Backend: FastAPI, SQLAlchemy, PostgreSQL (Supabase)
  • AI: Codex + GPT-5.6 (development), Groq (runtime)
  • Integrations: WhatsApp Business Cloud API, ReportLab, Resend/Gmail, Supabase Storage

One architectural decision we're particularly proud of is our two-phase execution model. The AI first creates an execution plan, but the final WhatsApp response is generated only after every tool has completed successfully. This ensures users receive verified execution results rather than assumptions.

Challenges we ran into

One of our biggest challenges was preventing hallucinations. The planner occasionally invented customer information when data was missing. We solved this by combining prompt-level constraints with backend validation, ensuring Foreman asks for missing information instead of guessing.

We also improved multi-turn conversations by introducing conversational memory while preventing customer information from leaking between requests.

Finally, we moved away from a fully serverless architecture after discovering that persistent WebSocket connections and background tasks were significantly more reliable on an always-running FastAPI backend.

Accomplishments that we're proud of

  • Built a real AI employee that performs business operations through WhatsApp.
  • Created an end-to-end workflow spanning CRM, invoicing, scheduling, email, and reminders.
  • Designed a modular architecture where new tools can be added easily.
  • Used Codex with GPT-5.6 to significantly accelerate development, debugging, testing, and documentation.
  • Built a live dashboard that mirrors every workflow execution in real time.

What we learned

We learned that prompts alone are not enough for production AI systems. Every AI-generated action must be validated before affecting real business data.

We also experienced how AI-assisted development with Codex and GPT-5.6 can dramatically speed up engineering, allowing us to spend more time on architecture and user experience instead of boilerplate implementation.

What's next

Our roadmap includes:

  • Google Calendar synchronization
  • GST-compliant invoicing
  • Proactive payment and maintenance reminders
  • Role-based employee permissions
  • Industry-specific workflow templates
  • Additional CRM and accounting integrations

Our long-term vision is to make Foreman feel like a reliable digital employee that helps small businesses automate their daily operations through the communication platform they already use: WhatsApp.

Built With

Share this project:

Updates