# Run coding agents from your app.

TypeScript SDK for Claude Code + Codex

Drive Claude Code and Codex, answer their prompts and let them hand work to each other through one local API.

How it fits · everything runs on your machine

Your app → jg-agent-hq → Claude Code + Codex

## Everything your agent UI needs.

### Drive native sessions

Create, resume, fork or close sessions, and steer, queue or interrupt the running turn.

`thread-create` · `message` · `steer` · `queue` · `interrupt` · `thread-fork`

[Session walkthrough](https://jg-agent-hq.jesusgraterol.dev/examples/#control-session)

### Answer prompts from your UI

Permission requests and agent questions wait in one inbox across restarts, and unknown kinds are denied.

`approvals` · `native-reply`

### See output, history and usage

Follow live output, browse past sessions and read each account’s real quota, credits and earned resets.

`live-items` · `sessions` · `session-evidence` · `usage` · `models`

### Let agents work together

Codex builds, Claude Code reviews with jg-review-session under an HQ grant, and HQ carries the report back.

Illustrative · build a CSV export, then review it

Your app has allowed Codex to build and Claude Code to review this task.

**You to Codex (task)**

Add CSV export to reports. Ask Claude to review it before you finish.

You give the task once. The agents handle the handoff.

**Codex to Claude Code (request)**

The exporter is ready. Check quoted fields and empty exports in src/reports/csv.ts.

`hq_message_publish` · HQ delivers the request. Codex waits for the review.

**Claude Code to Codex (report)**

Quoted fields work. An empty export loses its column headers.

`jg-review-session` · HQ grants the review skill, saves the full report and resumes Codex.

**Codex to You (result)**

Empty exports now keep their headers. I added a regression test, and it passes.

`hq_report_read` · Codex reads the report, makes the fix and finishes your original task.

`task-create` · `hq_message_publish` · `hq_invocation_read` · `hq_report_read` · `hq_agent_spawn`

[Review walkthrough](https://jg-agent-hq.jesusgraterol.dev/examples/#review-handoff)

### Change the plan, keep the work

Plans pass jg-plans checks before each approval, and verified milestones carry over when you revise them.

`approve` · `authorize` · `begin-revision` · `finalize`

[Revision walkthrough](https://jg-agent-hq.jesusgraterol.dev/examples/#revise-plan)

### Local, private and recoverable

HQ keeps its records in one private SQLite file you can share, snapshot while agents work and restore.

`hq.storage` · `createHqSnapshot` · `inspectHqSnapshot` · `restoreHqSnapshot`

## The rest of the toolkit.

### Accounts and MCP

Read native accounts, start sign-in and list a session’s MCP servers and tools.

`account-login`

### Models and settings

List models and effort choices, and read a session’s effective settings.

`models`

### Files and structured results

Attach verified workspace files and request results that match your schema.

`outputSchema`

### Browser hosts

Closed contracts let a browser app act through your trusted Node host.

`jg-agent-hq/contracts`

### Custom providers

Register another agent CLI behind the same session interface.

`IAgentProvider`

### Session tools

Fork, compact, archive, revert and name sessions, each with a durable receipt.

`thread-fork`

## Running in three commands.

- Node.js 24.15 or later
- Linux or macOS
- Claude Code or Codex, signed in

### Install

```sh
npm install jg-agent-hq@8.0.2
```

### Start the controller

```sh
./node_modules/.bin/jg-agent-hq serve --state-root .runtime --workspace-root .
```

### Check it’s running

```sh
./node_modules/.bin/jg-agent-hq status --state-root .runtime
```

[Send your first task](https://jg-agent-hq.jesusgraterol.dev/examples/#control-session) · [API reference](https://jg-agent-hq.jesusgraterol.dev/docs/api/) · [Source](https://github.com/jesusgraterol/jg-agent-hq)