giljo-hq

<div align="center">

<img src="docs/images/giljo-logo.png" alt="Giljo HQ" width="420">

<br>

**Context engineering platform for AI-assisted software development.**
<br>
Define your product once. Every agent that connects gets the full picture.

<br>

[![Python](https://img.shields.io/badge/Python-3.12%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-009688?style=flat-square&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com/)
[![Vue 3](https://img.shields.io/badge/Vue%203-4FC08D?style=flat-square&logo=vuedotjs&logoColor=white)](https://vuejs.org/)
[![Node.js](https://img.shields.io/badge/Node.js-22%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL%2018-336791?style=flat-square&logo=postgresql&logoColor=white)](https://www.postgresql.org/)
[![License](https://img.shields.io/badge/License-Elastic%20License%202.0-ffc300?style=flat-square&labelColor=0e1c2d)](LICENSE)
[![Setup](https://img.shields.io/badge/Setup-6--10%20min-6bcf7f?style=flat-square&labelColor=0e1c2d)](docs/INSTALLATION_GUIDE.md)
[![MCP Conformance](https://img.shields.io/badge/MCP%20Spec-Conformance-3a8ee6?style=flat-square&labelColor=0e1c2d)](docs/CONFORMANCE.md)
[![Backend CI](https://github.com/giljoai/giljo-hq/actions/workflows/ci.yml/badge.svg)](https://github.com/giljoai/giljo-hq/actions/workflows/ci.yml)
[![Frontend CI](https://github.com/giljoai/giljo-hq/actions/workflows/frontend.yml/badge.svg)](https://github.com/giljoai/giljo-hq/actions/workflows/frontend.yml)
[![CodeQL](https://github.com/giljoai/giljo-hq/actions/workflows/codeql.yml/badge.svg)](https://github.com/giljoai/giljo-hq/actions/workflows/codeql.yml)

<br>

**Free Community Edition** · Self-Hosted · Privacy First · Bring Your Own AI

**Works with:** Claude Code CLI · Claude.ai / Desktop · Codex CLI · ChatGPT.com · Any MCP Client

<br>

[Website](https://giljo.ai) · [Getting Started](https://giljo.ai/getting-started.html) · [Documentation](#documentation) · [User Guide](docs/USER_GUIDE.md)

</div>

<br>

<div align="center">
<img src="docs/images/staging-view.png" alt="Giljo HQ Jobs board: a staged chain of two linked projects, with the execution mode and Implement chain at the top" width="100%">
<br>
<sub>The Staging view: write what you want done. GiljoAI generates the mission and assigns agents from your templates.</sub>
</div>

<br>

## What Is Giljo HQ

Giljo HQ, a GiljoAI product, is a passive context server for AI coding tools. It stores your product knowledge, generates structured prompts, and coordinates multi-agent workflows via the Model Context Protocol (MCP). It does not write code or call any AI model. Your AI coding tool does all reasoning and coding using your own subscription.

GiljoAI sits at the intersection of product thinking and development. Whether you are a developer learning to define what you build before you build it, or a product manager turning a specification into working software, the platform gives you a structured path from vision to execution. The clearer your product definition, the more effective every agent session becomes.

**Bring Your Own AI.** GiljoAI works with Claude Code CLI, Claude.ai / Desktop, Codex CLI, ChatGPT.com, or any MCP-compatible tool. On Hosted, most tools connect with a one-click browser sign-in; terminal tools can also use an API key, which is what Community Edition's Connect tab gives you. You can run multiple tools simultaneously.

<br>

## Quick Start

**Windows (PowerShell):**
```powershell
irm giljo.ai/install.ps1 | iex
```

**Linux / macOS:**
```bash
curl -fsSL giljo.ai/install.sh | bash
```

The installer checks for prerequisites, downloads the latest release, sets up the database, builds the frontend, and walks you through configuration. When done, run `python startup.py` to start the server. First run opens the Setup Wizard in your browser.

<details>
<summary>Manual install (advanced)</summary>

```bash
git clone https://github.com/giljoai/giljo-hq.git
cd giljo-hq
python install.py
python startup.py
```
Requires Python 3.12+, PostgreSQL 18+, Node.js 22.23.3+.
</details>

**Using VS Code?** This repo ships a `.vscode/mcp.json` pointing at your local
Giljo HQ install (`http://localhost:7272/mcp`) — open the folder and VS Code's
MCP integration picks it up automatically. No copy-pasting a connect command.

<br>

## The Six Pillars

### Your Tools, Your Subscription

GiljoAI never touches your AI credits. You bring your own Claude Code CLI, Claude.ai / Desktop, Codex CLI, ChatGPT.com, or any MCP-compatible tool, each with your own subscription. GiljoAI acts as a passive MCP server: your tool connects over HTTP, reads context and coordination data, and does all the reasoning and coding itself.

### Define Your Product

<div align="center">
<img src="docs/images/product-context.png" alt="Product context form with tech stack configuration" width="100%">
</div>

Create a Product to represent the software you are building. Fill in context fields: description, tech stack, architecture, testing strategy, and more. Upload a vision document and let your AI tool populate the fields automatically. Vision documents are the most impactful input you can give GiljoAI. A well-written product proposal gives every agent session a shared understanding of what you are building and why.

### Roadmap

<div align="center">
<img src="docs/images/section-roadmap.png" alt="Roadmap" width="100%">
</div>

The Roadmap turns a product's inactive projects and pending tasks into a single prioritized plan. Each item carries a risk and complexity score, so you can see what is safe to tackle next and what needs more thought first. Drag to reorder. Activate a project straight from the Roadmap to stage it, and GiljoAI assembles its bootstrap prompt the same way it does anywhere else in the dashboard. A task that turns out to be bigger than expected converts into a project in one step, keeping its position on the board.

### Projects and Missions

1. Create a project and describe what needs to be done.
2. Activate the project. GiljoAI assembles a bootstrap prompt from your product context, 360 Memory, and project description.
3. Paste the prompt into your CLI tool. The orchestrator plans the mission and spawns agents.
4. Agents report status back in real time. You monitor progress on the Jobs page.
5. When the project completes, GiljoAI writes a 360 Memory entry. The next project inherits that accumulated context.

### Skills and Agent Templates

One skill is installed on your machine during setup. Use it from your CLI without breaking flow:

| Skill | Claude Code | Codex CLI | What it does |
|---|---|---|---|
| **Projects and tasks** | `/giljo` | `$giljo` | Capture tasks, create or update projects, and look them up mid-session — one command routes both create and read |

Agent templates need no installation at all. The Agent Template Manager in the dashboard lets you customize agent profiles with roles, expertise, and chain strategies, and every agent your orchestrator starts is handed its own profile — role, instructions, rules, success criteria — by the server the moment it begins work. An edit applies to the very next agent you launch. To run an agent yourself instead, choose **Download profile (.md)** from its row menu and drop the Markdown into any tool.

### 360 Memory

<div align="center">
<img src="docs/images/section-360-memory.png" alt="360 Memory" width="100%">
</div>

Each completed project writes to 360 Memory automatically: what was built, key decisions, patterns discovered, and what worked. This is not a plugin; it is a core product behavior. Your next project starts with accumulated context from previous ones. You control how many memories back agents read through the context settings. Optionally enrich memory with git commit history. Search across summaries, outcomes, and decisions, or filter by tag or project, to find what happened before.

### Dashboard and Monitoring

<div align="center">
<img src="docs/images/implementation-view.png" alt="Jobs board during implementation: agents working, complete and silent, a project ready for review and one waiting for your decision" width="100%">
</div>

The Jobs page shows real-time agent activity: status, step progress, duration, and messages waiting. A message composer lets you talk directly to the orchestrator or broadcast to the entire agent team. All messages are logged in the MCP message system for auditability.

<br>

### Message Hub

<div align="center">
<img src="docs/images/section-message-hub.png" alt="Message Hub" width="100%">
</div>

The Message Hub is where agents coordinate across sessions and machines: persistent threads with participants, messages, and a baton that tracks whose turn it is. An agent on a different CLI tool or a different machine can join the same thread and pick up right where another left off. The dashboard view of a thread is an audit record for you to read. Nothing shown there is fetched back into an agent's context automatically.

<br>

## Edition

This is the **Giljo HQ Community Edition**, free for single-user use under the [Elastic License 2.0](LICENSE).

| Community Edition (Free) | SaaS Edition |
|---|---|
| Self-hosted on your machine | Managed hosting: nothing to install |
| Full context assembly and agent coordination | Everything in CE, plus: |
| 6 agent templates + customization | Sign in with Google or GitHub |
| Real-time dashboard and monitoring | Nightly encrypted backups you can download or restore |
| Unlimited projects, up to 16 active agent slots | Self-service Solo subscription and billing |
| No telemetry, no cloud dependency | Managed updates: always on the latest version |

<br>

## Tech Stack

| Layer | Technology |
|---|---|
| **Backend** | Python 3.12+, FastAPI, SQLAlchemy 2.1 (async), Alembic |
| **Database** | PostgreSQL 18 (required) |
| **Frontend*