This project offers an AI-powered companion for Homebox inventory management, enabling users to photograph items for automatic identification and cataloging. It targets Homebox users seeking a more efficient way to manage physical assets, providing an AI chat interface for effortless organization, searching, and updating of inventory.

How It Works

The system leverages AI vision, specifically OpenAI's GPT-5 models accessed via the LiteLLM library, to process user-submitted photos. Users log into their Homebox instance, select a location, and capture or upload images of items. The AI analyzes these images to identify items, quantities, and relevant metadata. Users can then review, edit, or request AI corrections for the suggestions before submitting the finalized item details to their Homebox inventory. This approach eliminates manual data entry and speeds up the cataloging process.

Quick Start & Requirements

• Primary install / run command: Docker is recommended. A docker-compose.yml example is provided. A demo mode is available via docker run -p 8000:8000 -e HBC_LLM_API_KEY=sk-your-key -e HBC_HOMEBOX_URL=https://demo.homebox.software ghcr.io/duelion/homebox-companion:latest.
• Non-default prerequisites and dependencies: An OpenAI API key is required. A Homebox instance (tested with v0.21+) is necessary.
• Links: Demo server accessible at http://localhost:8000 after running the demo Docker command.

Highlighted Details

• AI-Powered Detection: Automatically identifies multiple items from a single photo, extracts details like manufacturer, model, serial number, and price, and suggests relevant tags.
• Smart Workflow: Supports multi-image analysis for better accuracy, single-item mode, AI-driven corrections, and custom thumbnail generation.
• AI Chat Assistant: Enables natural language queries for inventory management and actions (create, update, move, delete items) through an approval workflow. The assistant has access to 21 tools for interacting with the Homebox inventory.
• LiteLLM Integration: Facilitates easy integration with OpenAI GPT models (GPT-5 mini/nano) and offers experimental support for other LiteLLM-compatible providers and local models, provided they support vision capabilities.

Maintenance & Community

No specific details regarding notable contributors, sponsorships, community channels (like Discord/Slack), or roadmap links are present in the provided README.

Licensing & Compatibility

This project is licensed under the GNU General Public License v3.0 (GPL v3.0). This copyleft license may impose restrictions on commercial use and linking with closed-source software.

Limitations & Caveats

The service relies on external OpenAI API calls, incurring costs estimated between ~$0.10-$0.30 per 100 items depending on the model used. Experimental capture limits are noted, and non-OpenAI LLM providers are not officially supported. Native camera QR code detection requires HTTPS. The project is an unofficial third-party companion app, not affiliated with the core Homebox project.