@aithericon/hpi

Human-in-the-loop tasks for AI agents. One package — MCP server + CLI.

Your AI agent gets a comprehensive set of tools to create tasks, ask questions, collect approvals, upload files, and orchestrate multi-step workflows. Humans complete them through a web dashboard or magic links. Results flow back to the agent in real time.

Quick Start

npx @aithericon/hpi login
npx @aithericon/hpi setup claude-code

Restart your IDE. Done — your agent can now talk to humans.

What just happened?

1. hpi login opened your browser, you signed in (free account), and a token was saved to ~/.hpi/config.json
2. hpi setup claude-code wrote the MCP server config into .mcp.json in your project
3. When your IDE starts, it runs npx @aithericon/hpi which connects to HPI using the saved token

IDE Setup

npx @aithericon/hpi setup claude-code   # Claude Code
npx @aithericon/hpi setup cursor        # Cursor
npx @aithericon/hpi setup windsurf      # Windsurf

Or configure manually in your IDE's MCP config:

{
	"mcpServers": {
		"human-tasks": {
			"command": "npx",
			"args": ["-y", "@aithericon/hpi"]
		}
	}
}

Remote Approvals (Claude Code)

Approve or deny Claude Code's tool calls from your phone or browser — no need to sit at the terminal.

npx @aithericon/hpi setup claude-code --hooks

This configures Claude Code hooks that route permission requests through HPI:

1. Claude Code asks for permission → terminal dialog appears as usual
2. After 3 minutes with no response, an HPI task is created
3. You approve or deny from the HPI dashboard (phone, browser, anywhere)
4. The decision flows back to Claude Code automatically

If you respond in the terminal instead, the HPI task is automatically cancelled on the next tool call.

How cancellation works

Claude Code currently has no hook that fires when you respond to a permission dialog (GitHub #19628). Cleanup is eventually consistent — it runs on the next tool call or when the session ends:

• You respond within 3 minutes → no HPI task is ever created
• You respond after the task is created → the task is cancelled on the next tool call
• You respond via HPI → Claude Code receives the decision immediately

Configuration

| Env var | Default | Description | |---------|---------|-------------| | HPI_HOOK_DELAY | 180 | Seconds to wait before creating an HPI task | | HPI_HOOK_WAIT | 14400 | Max seconds to poll for an HPI response (4 hours) |

CLI Commands

hpi                         Start MCP server (default, used by IDEs)
hpi login [--url URL]       Authenticate with cloud or self-hosted instance
hpi logout                  Remove stored credentials
hpi setup <ide>             Configure IDE MCP settings (project-scoped)
hpi setup <ide> --global    Configure IDE MCP settings (global/user-wide)
hpi setup <ide> --hooks     Also configure remote approval hooks (claude-code only)
hpi status                  Show current connection info

Self-Hosted

Connect to your own instance instead of the cloud:

npx @aithericon/hpi login --url https://hpi.yourcompany.com

Or set environment variables (useful in CI/server contexts):

export HPI_URL=https://hpi.yourcompany.com
export HPI_TOKEN=htk_your-api-token

MCP Tools

Once connected, your AI agent can use these tools:

| Tool | What it does | | ----------------------- | -------------------------------------------------------------------- | | create_task | Create a task with steps, fields, and blocks | | ask_question | Ask a human a free-text question and wait for the answer | | ask_approval | Request yes/no approval with optional details | | ask_choice | Present multiple options and get a selection | | ask_for_review | Show content for review with verdict + feedback | | send_image | Upload and show an image, collect feedback | | send_document | Upload a document (PDF inline viewer), collect feedback | | get_task | Get task status, completion data, and optionally the full definition | | wait_for_task | Block until a task is completed/failed/cancelled | | list_tasks | List tasks with optional filters | | cancel_task | Cancel a pending task | | send_reminder | Re-send notification to assignee | | create_task_from_file | Create a task from a JSON file definition on disk | | begin_task | Start building a multi-block task | | add_md | Add markdown to a draft task | | add_image | Add an image to a draft task | | add_file | Add a file to a draft task | | add_input | Add a form field to a draft task | | add_callout | Add an alert/callout to a draft task | | add_table | Add a data table to a draft task | | submit_task | Submit a draft task and wait for completion | | create_process | Create a tracked multi-step process | | list_processes | List processes with optional filters | | get_process | Get process state and timeline | | update_process | Push step transitions and progress updates |

Programmatic Usage

import { HPIClient } from '@aithericon/hpi/client';

const client = new HPIClient('https://app.hpi.dev', 'htk_your-token');

const task = await client.createTask({
	title: 'Review deployment plan',
	steps: [
		{
			id: 'review',
			title: 'Review',
			blocks: [
				{ type: 'mdsvex', content: 'Please review the deployment plan for **v2.1**.' },
				{ type: 'input', field: { name: 'approved', label: 'Approve?', kind: 'checkbox' } }
			]
		}
	]
});

// Wait for the human to complete it
const result = await client.waitForTask(task.task_id);
console.log(result.data); // { approved: true }

License

Apache License 2.0