Skip to main content
jg-agent-hq
Source (opens in a new tab)

TypeScript SDK for Claude Code + Codex

Run coding agents from your app.

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

See what it does Set up locally
How it fits · everything runs on your machine

Your appDashboard, editor or automation

Commands

thread-createmessagenative-reply

Results

live-itemsapprovalsusage

jg-agent-hqLocal controller

  • Sessions
  • Prompts
  • Streams
  • Plans

Native control

Agent tools

hq_message_publishhq_agent_spawn

  • Claude Code
  • Codex

Native sign-in, tools and skills

What it does

Everything your agent UI needs.

01

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

Illustrative session · every action reports its delivery

build-reports

Codex
  1. thread-createOpen a session in reports-workspaceacknowledged
  2. messageExplain how this repository generates reports.acknowledged
  3. steerFocus on the PDF exporter.acknowledged
  4. queueThen add a test for it.queued

02

Answer prompts from your UI

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

  • approvals
  • native-reply
Illustrative · a Codex permission prompt
Waiting for youbuild-reports · Codex

Run a command

pnpm test --filter reports

Your app replies with one decision

  • accept
  • acceptForSession
  • decline
  • cancel

Inbox1 pending3 answered1 expired

03

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
Illustrative · usage, credits and session history

Claude Code

  • 5-hour windowall models46% used · resets 15:00

  • 7-day windowOpus21% used · resets Monday

Codex

  • 5-hour window38% used · resets 14:20

  • 7-day window12% used · resets Monday

Credit balance
120
Earned resets
1 available

Sessions

Read-only · nothing resumes
  • build-reportsCodex · Running
  • fix-loginClaude Code · Yesterday
  • docs-refreshClaude Code · 3 days ago

04

Let agents work together

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

  • task-create
  • hq_message_publish
  • hq_invocation_read
  • hq_report_read
  • hq_agent_spawn

Review walkthrough

Illustrative · build a CSV export, then review it

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

  1. You

    tasktoCodex

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

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

  2. Codex

    requesttoClaude Code

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

    hq_message_publishHQ delivers the request. Codex waits for the review.

  3. Claude Code

    reporttoCodexgranted skill jg-review-session

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

    HQ grants the review skill, saves the full report and resumes Codex.

  4. Codex

    resulttoYou

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

    hq_report_readCodex reads the report, makes the fix and finishes your original task.

05

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

Illustrative · checked approvals, then a revision

Checked by jg-plans at every approval

  1. Plan approvedplan.md passes check
  2. Sequence refusedJG_AGENT_HQ_PLAN_INVALIDno milestone covers AC-04
  3. Sequence approvedthe new breakdown covers AC-04
  4. Execution authorized

Then a revision adds one requirement

Before

  • Greeting

    Verified

After

  • Greeting result

    Verified · same ID, evidence kept

  • Report

    Pending · new requirement

Then fresh approvals, each one explicit

  1. Plan approved
  2. Milestones approved
  3. Execution authorized

06

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
Illustrative state root · .runtime

hq.sqlite

  • hq_*Receipts, streams and reports
  • app_*Your app’s own tables

action.key private, kept with the database

  1. createHqSnapshot

    Captured while agents work

  2. restoreHqSnapshot

    New folder, automation paused

Also included

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

Get started

Running in three commands.

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

Send your first task

  1. 01

    Install

    Install

    npm install jg-agent-hq@8.0.2

  2. 02

    Start the controller

    Start the controller

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

  3. 03

    Check it’s running

    Check it’s running

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