Human-Agent Interactive Collaboration Orchestrator (HAICO)

A shared workspace for humans and AI agents

Run multi-agent projects with built-in issues, approvals, knowledge, and live dashboards, while keeping humans in the loop.

Website · Quick Start · Product Tour · Key Features · How It Works · Contributing

The Problem

You have several complex projects. You spin up multiple AI agents. They move fast, but without shared context and oversight, they drift, duplicate work, and burn tokens. Agents alone are not enough for complex workflows. Humans need to stay in the loop.

The Solution

HAICO creates a shared workspace where humans and AI agents collaborate as a team. A controller decomposes work, workers execute it, and the dashboard keeps humans in the loop with issues, approvals, knowledge, terminals, files, and usage in one place. Think of it as GitHub Issues + agent orchestration with human oversight in one platform.

                    ┌──────────────┐
                    │  Controller  │  Decomposes tasks, assigns work
                    │    Agent     │  monitors progress
                    └──────┬───────┘
                           │ creates & assigns issues
              ┌────────────┼────────────┐
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │ Worker 1 │ │ Worker 2 │ │ Worker N │
        │ (Claude) │ │ (Codex)  │ │  (Any)   │
        └──────────┘ └──────────┘ └──────────┘
              │            │            │
              └────────────┴────────────┘
                    Shared Issue Tracker
                    Knowledge Base & Agent Knowledge
                    Real-time Web Dashboard

Product Tour

Why HAICO?

| | Single Agent | HAICO | |---|---|---| | Task Complexity | Gets lost on multi-step projects | Controller decomposes, workers execute in parallel | | Context Window | One agent carries everything | Each agent focuses on its assigned scope | | Cost Control | Burns tokens on tangents | Token budgets, tail-request detection, auto-cooldown | | Coordination | N/A | Issue tracker, knowledge base, direct messaging | | Visibility | Black box | Real-time terminal, issue timeline, cost dashboard | | Persistence | Session dies, context lost | Agent-owned knowledge survives across sessions |

Key Features

Orchestration

• Hierarchical agent teams with controller/worker roles and parent-child relationships
• Two orchestration engines: Native (direct) and LangGraph (agentic reasoning with tool use)
• Cron-based scheduling for recurring agent tasks

Collaboration

• Built-in issue tracker with priorities, labels, assignments, dependencies, and sub-issues
• Shared knowledge base — high-importance entries auto-injected into agent prompts
• Per-agent owned knowledge items that persist across sessions
• Direct messaging between agents
• Human approval gates for higher-risk agent actions

Operations

• Process lifecycle management with watchdog detection for stuck agents
• Token budgets with tail-request avoidance to prevent runaway costs
• Session persistence with auto-resumption and cooldown

Dashboard

• Real-time terminal via xterm.js + WebSocket
• Issue management with full comment timelines
• File upload, download, and preview (PDF, HTML)
• Multi-user auth with role-based access control

Quick Start

Prerequisites

• Node.js >= 18

Option 1: Global Install (recommended)

npm install -g haico
haico

That's it. Open http://localhost:4567.

# CLI options
haico --port 8080 --host 0.0.0.0 --db ./my-project.db --no-auth

Option 2: Clone & Run

git clone https://github.com/fuzihaofzh/haico.git
cd haico
npm install

# Development (auto-reload)
npm run dev

# Production
npm run build && npm start

On first visit, you'll be prompted to create an admin account.

Configuration

| Variable | Default | Description | |----------|---------|-------------| | HAICO_PORT | 4567 | Server port | | HAICO_HOST | 0.0.0.0 | Bind address | | HAICO_DB_PATH | ./haico.db | SQLite database path | | HAICO_ORCHESTRATOR_ENGINE | langgraph | native or langgraph | | HAICO_NO_AUTH | false | Disable authentication |

How It Works

1. Create a Project

Define a project with a task description — this is the mission your agent team will tackle.

2. Set Up Your Team

• Add a Controller agent — it reads the task, creates issues, and assigns work
• Add Worker agents — each with a role, working directory, and optional custom instructions
• Agents can be organized hierarchically (parent-child relationships)

3. Launch

Start the controller. It will:

1. Analyze the project task
2. Decompose it into issues on the built-in tracker
3. Assign issues to worker agents
4. Start workers and monitor progress
5. Coordinate until the project is complete

4. Monitor Everything

The web dashboard gives you full visibility — real-time terminal output, issue timelines, knowledge base, file browser, and cost tracking.

Architecture

┌─────────────────────────────────────────────────┐
│              Web Dashboard (HTML/JS)             │
│   Projects · Agents · Issues · Terminal · Files  │
└────────────────────┬────────────────────────────┘
                     │ HTTP + WebSocket
┌────────────────────▼────────────────────────────┐
│                Fastify Server                    │
│                                                  │
│  Routes ─── Auth ─── WebSocket                   │
│    │                                             │
│  Services                                        │
│    ├── Orchestrator (Native / LangGraph)         │
│    ├── Controller & Pre-Controller               │
│    ├── ProcessManager (spawn, pty, lifecycle)     │
│    ├── Scheduler (cron, watchdog)                │
│    ├── Terminal (xterm.js bridge)                │
│    └── Agent Hierarchy                           │
│    │                                             │
│  SQLite (better-sqlite3)                         │
│    projects · agents · issues · knowledge ·      │
│    messages · users · sessions                   │
└──────────────────────────────────────────────────┘

Tech Stack: TypeScript · Fastify · SQLite · LangChain/LangGraph · xterm.js · WebSocket

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

# Dev mode with auto-reload
npm run dev

# Build
npm run build

# Run tests
npm test

License

MIT

Built for teams where humans and agents work side by side.

GitHub · npm