Set up Giljo HQ and put it to work.
Giljo HQ holds your product context, stages projects for your AI coding tools, and keeps a 360 Memory of what shipped. This guide covers getting started, connecting your tools, installing the Community Edition and every MCP tool.
What Giljo HQ is, and its two editions.
Giljo HQ is a passive MCP server for AI coding tools. It holds your product knowledge, turns your project descriptions into structured prompts, and coordinates a crew of agents through the Model Context Protocol. It never calls an AI model and never writes code itself: your own AI coding tool does the reasoning and coding, on your own subscription.
What is inside
- Products. One definition of the software you are building: description, tech stack, architecture, testing, and vision documents. Every agent reads it.
- Projects and tasks. A project is work you run with agents; a task is a note about work for later. Handovers record where a session stopped.
- The Jobs board. Stage a project, launch it in your tool, and watch every agent's status, steps and messages live.
- Roadmap. One ranked list of what to build next, scored by your agent for risk and complexity.
- Chains. Link 2 to 10 projects to run one after another under one goal.
- Message Hub. Threads where you and your agents talk, with a baton that shows when it is your turn.
- 360 Memory. Every finished project writes what was built and decided, and the next project starts with that history.
- Agent templates. 15 roles of your own plus the reserved orchestrator, active per product. Each agent gets its profile from the server when it starts work.
- The
/giljocommand. Create, update and look up projects and tasks without leaving your coding tool.
Editions
Hosted
Runs at app.giljo.ai. Nothing to install: the server, database, updates and nightly encrypted backups are managed for you. Sign in with email, Google or GitHub, and connect your tools with browser sign-in. See Pricing for plans.
Community Edition
Free and self-hosted on your own machine and PostgreSQL database; your data never leaves it. Source-available under the Elastic License 2.0. It serves plain HTTP on localhost and your network by default, connects tools with API keys, and you run the updates and backups. See Install Community Edition.
Both editions are single-user: one account per person.
From sign-up to your first finished project.
1. Create an account
On Hosted, sign up at app.giljo.ai with your email, or with Google or GitHub. With email, we send a link to set your password; it expires in 1 hour. See Pricing for the free trial and plans. On the Community Edition, install it first, then open the dashboard.
2. Run the Setup Wizard
The Setup Wizard opens the first time you sign in. You can rerun it any time from Tools > Startup.
| Step | What happens |
|---|---|
| Choose tools | Pick one or more of Claude Code, Codex CLI, OpenCode or a generic MCP client. You can add the rest later. |
| Connect | The wizard shows a one-command setup for each tool, one at a time. Its status card turns green by itself when the tool connects. Already set one up? Choose I already configured this. |
| Install | Ask your tool to call the giljo_setup tool. It installs the /giljo command and writes a short Giljo HQ block into your project's CLAUDE.md or AGENTS.md. Text outside that block is left alone. |
| Launch | Four cards: create your first product, open the dashboard, read the guide, or drive from your terminal. |
The commands for every tool are under Connect your tools.
3. Create your first product
After the wizard, a short welcome tour opens. It ends by offering four ways to create your first product:
- I have an existing codebase. One prompt, and your connected agent reads the repository, writes the vision document and fills in the product for you.
- I have an idea, help me shape it. A short guided interview with your agent turns your idea into a product.
- I have a vision document. Upload a
.mdor.txtbrief and it becomes your product. - I'll fill it in myself. Opens the product form.
4. Stage and run a project
- Open Projects, click New project, and describe what you want built in plain language. Pick a project type such as BE or FE for its serial badge.
- Activate the project. Its card appears on the Staging side of the Jobs board.
- On the card's Run as row, choose Multi-terminal or Subagent. Nothing is chosen for you.
- Click Stage Project. Giljo HQ copies a prompt built from your product context, 360 Memory, project description and agent templates. Paste it into your coding tool; the orchestrator plans the mission and picks the crew.
- Click Implement. It copies the implementation prompt for you to paste, and the card moves to the Implementation side.
- Watch each agent's status, steps and messages on the card. If an agent needs a decision, the card says Your decision needed.
- When every agent has finished, click Review project, read the closeout summary, and click Close. The project's 360 Memory entry carries into your next project.
5. Work from your terminal
The /giljo command lets you talk to your board in plain language:
The User guide covers every screen in detail.
Add Giljo HQ to the tools you already use.
Giljo HQ connects to Claude Code, Codex CLI, OpenCode and any other MCP client, under the server name giljo_hq. The in-app Setup Wizard and Tools > Connect show the same commands with your own server address filled in. Choose your edition and how you want to sign in:
Get an API key. In the app, open Tools > Connect, pick the tool and click Generate API Key (Generate New Config on the Generic MCP client card); on Hosted, choose Use an API key instead on the tool's card first. Replace <your-api-key> below with it. Each key expires after 90 days, you can hold as many as you need, and you can revoke any of them.
Community Edition address. The commands use http://localhost:7272/mcp, the default on the machine that runs Giljo HQ. If your tool runs on another machine, use your server's address and port instead.
Prefer to let your agent do it? Give it this link: https://app.giljo.ai/connect.md. It tells the agent which commands to run for its own tool.
Prefer to let your agent do it? Give it your own server's /connect.md address. It tells the agent which commands to run for its own tool.
Claude Code
Anthropic's command-line coding tool.
Add the server. Then run /mcp inside Claude Code and choose to authenticate; a browser window opens for sign-in.
Add the server with your API key.
$ claude mcp add --scope user --transport http giljo_hq https://app.giljo.ai/mcp --header "Authorization: Bearer <your-api-key>"Add the server with your API key.
$ claude mcp add --scope user --transport http giljo_hq http://localhost:7272/mcp --header "Authorization: Bearer <your-api-key>"Codex CLI
OpenAI's command-line coding tool.
Add the server. Codex detects the sign-in when you add it and opens your browser.
$ codex mcp add giljo_hq --url https://app.giljo.ai/mcpStore your API key in the GILJO_API_KEY environment variable, then add the server. Codex reads the key from that variable.
Store your API key in the GILJO_API_KEY environment variable, then add the server. Codex reads the key from that variable.
OpenCode
A command-line coding tool.
Add the server, then sign in. The second command opens your browser.
$ opencode mcp add giljo_hq --url https://app.giljo.ai/mcp $ opencode mcp auth giljo_hqAdd the server with your API key. OpenCode writes the header as Authorization=Bearer, with an equals sign.
Add the server with your API key. OpenCode writes the header as Authorization=Bearer, with an equals sign.
Claude Desktop and claude.ai
Claude in the desktop app or the browser.
Add a custom connector in Settings > Connectors with the address below. It signs in through the browser.
https://app.giljo.ai/mcpClaude Desktop can reach the server with an API key through the mcp-remote bridge, which needs Node.js. Open Settings > Developer > Edit Config and add this to claude_desktop_config.json, then restart Claude Desktop. This works in the desktop app only, not on claude.ai.
Claude Desktop can reach the server with an API key through the mcp-remote bridge, which needs Node.js. Open Settings > Developer > Edit Config and add this to claude_desktop_config.json, then restart Claude Desktop. This works in the desktop app only, not on claude.ai.
ChatGPT, IDEs and other web connectors
Apps that add an MCP server by its URL.
- Paste the URL below into the app's MCP connector settings.
- Sign in when your browser opens. No key needed.
Web connectors sign in through your browser. If your app takes an Authorization header instead, use the Any MCP client configuration below.
The Community Edition connects every tool with an API key. If your app or IDE accepts an Authorization header, use the Any MCP client configuration below.
Any MCP client
Any other client that speaks MCP over Streamable HTTP. In the app this is the Generic MCP client card.
A client that supports MCP OAuth with dynamic client registration needs only the server address (Streamable HTTP). The server advertises OAuth at https://app.giljo.ai/.well-known/oauth-authorization-server.
A client without it connects with an API key: on the app's Generic MCP client card, click Generate New Config and add the result to the client's MCP settings. It looks like this:
{ "giljo_hq": { "transport": "streamable-http", "url": "https://app.giljo.ai/mcp", "headers": { "Authorization": "Bearer <your-api-key>" } } }On the app's Generic MCP client card, click Generate New Config and add the result to the client's MCP settings. It looks like this:
{ "giljo_hq": { "transport": "streamable-http", "url": "https://app.giljo.ai/mcp", "headers": { "Authorization": "Bearer <your-api-key>" } } }On the app's Generic MCP client card, click Generate New Config and add the result to the client's MCP settings. It looks like this:
{ "giljo_hq": { "transport": "streamable-http", "url": "http://localhost:7272/mcp", "headers": { "Authorization": "Bearer <your-api-key>" } } }Check the connection
In the app, a tool's status turns green by itself once it connects. To check by hand, restart or reload your tool if it asks, then confirm giljo_hq is connected, for example with claude mcp list, codex mcp list or opencode mcp list, or ask your agent to run the health_check tool.
Then call giljo_setup
Once connected, have your agent call the giljo_setup tool. It installs the /giljo command and writes the Giljo HQ block into your project's CLAUDE.md or AGENTS.md. This is also the Setup Wizard's Install step (see Getting started).
Some connections are given a smaller set of tools than others, so one client may show fewer Giljo HQ tools than another. That is expected.
Run Giljo HQ on your own machine.
The installer downloads the latest release, checks for prerequisites, sets up the database, builds the dashboard and walks you through configuration. It offers to install Python and PostgreSQL if they are missing; on Linux it installs them through your package manager.
Prefer to read a script before you run it? Download it from the same address, inspect it, then run it.
When the installer finishes, start the server. The first start opens the Setup Wizard in your browser.
$ python startup.pyRequirements
- Python 3.12 or later
- PostgreSQL 18 or later
- Node.js 22 or later, to build the dashboard
- Windows, macOS or Linux
Manual install
To clone the source and run the installer yourself:
$ git clone https://github.com/giljoai/giljo-hq.git $ cd giljo-hq $ python install.py $ python startup.pyPorts and addresses
- The server and its MCP endpoint listen on port 7272: tools connect to
http://localhost:7272/mcp. Check it is up athttp://localhost:7272/health. - The dashboard runs on port 7274. The installer prints the address to open.
- If another program uses these ports, change
api_portanddashboard_portinconfig.yamlbefore starting.
Running it
python startup.py --verboseopens a live log window beside the server.python startup.py --setupforces the Setup Wizard to open.- Both installers accept
--repairto re-run over an existing install and fix a broken or partial setup. - To update, run
git pulland restart the server. Database migrations apply on restart.
HTTPS
Giljo HQ serves plain HTTP, which is fine on a trusted home or office network. For HTTPS, put a reverse proxy such as Caddy, Cloudflare Tunnel, Tailscale, nginx or Traefik in front of it, and never expose plain HTTP to the internet. After the address changes, set GILJO_PUBLIC_URL in .env, restart, and connect your tools again. The in-app User Guide has a worked Caddy example.
Every screen, explained.
The user guide walks through each part of the app: what you see, what each control does, and the limits you may meet.
Choosing the right way to run the work.
Project or task?
A task is a note: work you have spotted but not scheduled. It costs nothing and runs no agents. A project is work you run: it has a description, an agent crew, a mission and a closeout that writes a 360 Memory entry.
| Use a task when | Use a project when |
|---|---|
| You want to note work for later | You want agents to do the work now |
| It is a single step or a reminder | The work has several steps or phases |
| You are capturing debt or an idea mid-flow | You have a clear goal and want a plan |
| You do not need a plan or agents yet | You want a 360 Memory entry at the end |
When in doubt, start with a task. When it is ready, open it and choose Convert to Project; the new project arrives inactive, and you activate it when you are ready. A handover is different again: a record of where a session stopped, for whoever picks it up next.
Multi-terminal or subagent?
| Multi-terminal | Subagent | |
|---|---|---|
| Terminals you open | One per agent | One |
| Who launches each agent | You | The orchestrator |
| Best for | Supervising agents one by one, or across machines | A single guided session |
In multi-terminal mode, phases run one after another and agents within a phase run in parallel. Subagent mode works with tools that support subagents.
Chains
A chain links 2 to 10 projects and runs them one after another toward one goal, for example scaffold a service, build a feature on it, then harden it. Each project keeps its own description, agents and 360 Memory entry.
- On Projects, click Link projects (chain mode) and tick the projects to link. They run in the order they appear in the table.
- Click Run sequential (N/10). This queues the chain; the dashboard cannot start agents itself.
- An agent connected through your coding tool picks up the queued chain and becomes the conductor. It stages the first project, then waits for your go-ahead before implementation starts.
- Follow the chain as one group on the Jobs board: a Step n of N counter, the Chain goal, and a card per project. Review and close each finished project from its card.
Stop chain ends a running chain and keeps the work already done. Deactivate chain returns its projects to their earlier state so you can re-link and relaunch; completed projects keep their results and memory.
Driving from your terminal
Everything in the dashboard can also be done by asking your connected agent: create and activate a product, stage a project, launch implementation, or run a chain. The same server-enforced pause waits for your go-ahead before implementation, whichever way you start it, and the dashboard updates live either way. With several products open, your agent can act on any product by name.
Roadmap or projects list?
Use the Roadmap when you want your agent's view of what comes first: it ranks your inactive projects and pending tasks. Use the Projects list when you already know what to do: create, edit, activate, link into a chain or close out.
The Giljo HQ MCP tools, by area.
Giljo HQ registers 49 tools. Your client may see fewer: the server gives some connections a smaller tool profile.
| Tool | What it does |
|---|---|
| Discovery and health | |
health_check | Checks that the server is up. |
get_giljo_guide | Returns the routing and lifecycle guide your agent follows. |
| Project management | |
create_project | Creates a project. |
update_project | Changes a project's details. |
list_projects | Lists your projects. |
update_project_mission | Saves the orchestrator's mission for a project. |
diagnose_project_state | Checks a project's state without changing it. |
| Project lifecycle | |
stage_project | Prepares and stages a project. |
get_staging_instructions | Returns the orchestrator's staging directives. |
get_implementation_prompt | Returns the prompt that starts implementation. |
launch_implementation | Releases the human go-ahead before implementation. |
link_projects | Links projects into a chain. |
unlink_projects | Abandons a chain. |
write_project_closeout | Closes a project and writes its 360 Memory. |
| Tasks | |
create_task | Creates a task or a handover. |
update_task | Changes a task. |
list_tasks | Lists your tasks. |
| Roadmap | |
save_roadmap | Saves the order your agent ranked. |
get_roadmap | Reads the roadmap. |
| Agent jobs | |
spawn_job | Creates a job for a specialist agent. |
get_job_mission | Returns an agent's mission and its profile. |
update_job_mission | Edits an agent's plan. |
report_progress | Reports progress on an agent's to-do list. |
complete_job | Marks a job done. |
finalize_job | Accepts and seals the work. |
resume_or_dismiss_job | Resumes or dismisses a job on hold. |
set_agent_status | Marks an agent blocked, idle or sleeping. |
get_agent_result | Reads a finished agent's result. |
get_workflow_status | Shows progress across all agents. |
request_approval | Asks you for a decision. |
decide_approval | Answers a decision from your tool. |
| Message Hub | |
create_thread | Starts a thread. |
join_thread | Joins a thread. |
post_to_thread | Posts a message. |
get_my_turn | Lists the threads waiting on you. |
get_participant_liveness | Shows who is still active on a thread. |
set_next_actor | Passes the turn. |
list_threads | Finds and searches threads. |
update_thread | Renames a thread or changes its status or tags. |
get_thread_history | Reads a thread's timeline. |
| Context and memory | |
get_context | Fetches product and project context. |
search_memory | Searches 360 Memory by keyword. |
write_memory_entry | Writes a 360 Memory entry. |
| Vision and product context | |
create_product | Creates a product. |
create_vision_document | Writes a vision document. |
get_vision_document | Reads a vision document. |
update_product_context | Saves the product fields your agent extracted. |
apply_context_tuning | Applies context changes you approved. |
| Setup | |
giljo_setup | Installs the /giljo command and writes the Giljo HQ block into your project file. |
The words you will meet in the app.
| Term | Meaning |
|---|---|
| Product | The software you are building, and the top-level container: every project, task, agent and memory belongs to one product. It holds the context agents read at the start of each session. |
| Project | A focused unit of work inside a product, such as a feature, a refactor or a fix. It has a description, an agent crew, a mission and a closeout that writes a 360 Memory entry. |
| Task | A note about work you have identified but not scheduled. It runs no agents; convert it to a project when you are ready. |
| Handover | A record of where a working session stopped, for whoever picks it up next. It must list the claims to verify with the command that checks each one, what is waiting on you, and what the author could not confirm. |
| Job | One agent's assignment within a running project: its role, mission and to-do list. |
| Staging | The first side of the Jobs board. Pick an execution mode and click Stage Project to generate the orchestrator's prompt. |
| Implementation | The second side of the Jobs board, where a project's card moves once you click Implement and the agents do the work. |
| Agent | An AI worker running in your own coding tool, such as Claude Code, Codex CLI, OpenCode or another MCP client. Giljo HQ gives it a role and context; your tool does the work. |
| Orchestrator | The lead agent for a project. It reads your product context and 360 Memory, plans the mission, starts the specialist agents and coordinates them to closeout. |
| Agent template | The reusable definition behind an agent role. Each product can have 15 of your own roles active at once, plus the reserved orchestrator. |
| Role and expertise | The field on an agent template where you describe that agent's specialization. It shapes how the agent behaves. |
| Conductor | The agent that drives a chain. It owns no project of its own; it launches each linked project in order and advances to the next. |
| Chain | Two to ten projects linked and run one after another under one goal, the chain mission, shown as Chain goal on the Jobs board. |
| Thread | One conversation in the Message Hub. A project thread belongs to a project; a general thread stands alone. |
| Baton | Marks whose turn it is in a thread. When it is handed to you, the thread shows Your turn. |
| Roadmap | A ranked list, one per product, of your inactive projects and pending tasks, ordered by your agent. |
| Mission | What a project or an agent is trying to achieve. The orchestrator plans a project's mission from your description and context. |
| Vision document | A file describing your product, uploaded by you or written by your agent. It feeds the product's context. |
| 360 Memory | The record written at the end of each project: what was built, key decisions, patterns and outcomes. Your next project starts with it. |
| Archived | Hidden from the default view without being deleted. Archived items come back through search or Show archived. |
| Trash | Deleted projects, threads, vision documents and agent templates stay recoverable for a while before they are purged for good. |
Get help.
Questions, problems connecting, bug reports, privacy requests and security reports.
What to include
- The email address of your Giljo HQ account, and whether you use Hosted or the Community Edition.
- The version from the app's About dialog, if you self-host.
- The AI coding tool you use and its version.
- What you did, what you expected, and what happened, with the exact error text or a screenshot.
- The serial involved, such as a project's
BE-0042, a task'sTSK-0042or a thread'sCHT-0042. - Roughly when it happened, with your time zone.
Never send passwords, API keys or tokens. We will not ask for them.
Privacy and terms
Giljo HQ is covered by the GiljoAI Privacy Policy and Terms of Service.