Integrate Hokusai

Add intelligent model routing to the tools you already use. Choose where you want Hokusai to run, then follow the integration guide for your workflow.

Where do you want Hokusai to run?

Choose the environment you already work in.

Selected Integration Guide

AI Coding Agent / Claude Code

AI Coding AgentClaude CodeImplementation

Supported Today

Overview

Install a plugin inside your coding app.

Prerequisites

  • A Hokusai API key
  • A supported coding assistant installed locally
  • A shell where the assistant can read HOKUSAI_API_KEY

Installation

  1. Terminal
    Step 1

    Set your API key

    Claude Code only sees environment variables present when it starts. Export your key, then launch Claude Code from that shell.

    Get your API key
    Shell command
    export HOKUSAI_API_KEY=hk_live_your_key_here
claude
    Claude Code launched with Hokusai credentials
    Continue in Claude Code
  2. Claude Code
    Step 2

    Install the Hokusai plugin

    Add the repository marketplace source, install the plugin, then reload so the slash commands register.

    App command
    /plugin marketplace add Hokusai-protocol/hokusai-sdk
/plugin install hokusai@hokusai
/reload-plugins
    Plugin installed

Verify

  1. Claude Code
    Step 1

    Run the plugin doctor

    Run the doctor after reloading plugins to confirm credentials, connectivity, and command registration.

    App command
    /hokusai:doctor

    Expected output: Connected · Routing enabled · Ready

    Doctor passed

Next Steps

  1. Claude Code
    Step 1

    Route your first task

    Send one real task through the assistant before changing optional contribution settings.

    App command
    /hokusai:route Find the performance bottleneck in this function.
    First task routed
Shell commands and app commands are separated in each step.

Reference harness · Host integration

What your harness owns

If your harness isn’t listed above, follow the reference harness path — a working adapter template, not a raw API dump. Hokusai becomes the routing layer inside your loop; these four responsibilities stay with your harness.

1

Collect task context

Normalize your local task into a routing payload — description, task type, language, and complexity — before you call Hokusai.

2

Discover runnable models

Pass only the models your harness can actually execute as the candidate pool. Hokusai ranks within that set and never invents a model you did not offer.

3

Execute with the selected model

Hokusai recommends; your harness runs the model and owns the execution UX. Resolve the recommended id against your registry, then dispatch the task yourself.

4

Preview the redacted payload

Preview the anonymized dispatch payload before transport so you can see exactly what leaves your process. Raw prompt text is redacted at this step.

Recommendation mapping raises — it does not silently fall back

When the router names a model your harness cannot run, mapRecommendation() throws a ModelMappingError (UNKNOWN_MODEL, PROVIDER_NOT_ALLOWED, or MODEL_UNAVAILABLE). Catch it and either remap to an allowed model or record a decline. Do not assume a registry default — selected_models must describe the model that actually ran.

A contribution row is training-eligible only when it carries every field

A row missing budget or actual cost is still accepted, but filed as partial — telemetry that trains nothing and earns nothing.

  • inference_log_id threaded back unchanged from the route
  • budget_usd
  • actual_cost_usd
  • Non-empty task descriptors
  • Selected and allowed models

Fix in the SDK

Not host-specific

  • mapRecommendation() reference docs still describe a registry-default fallback, but the shipped SDK throws ModelMappingError. Align the docs (or the code) so hosts handle the error path.
  • OpenHands cost guidance: the OpenHands SDK exposes LLM and conversation metrics, so docs should not claim it lacks cost-signal surfaces. Price those token counts with computeActualCostUsd().

Host-specific

Your harness owns these

  • Collecting task context and building the routing payload.
  • Choosing the candidate model pool your harness can run.
  • Executing the selected model and owning the execution UX.
  • Previewing the redacted payload before transport.

Part 2 — Optional (~30 sec) · Contribution context

Accepted contribution rows are optional after routing.

Route first. Coding-agent plugins can contribute anonymized outcome reports after preview, while harness and application flows can submit accepted rows and surface the server's fidelity tier.

  1. 1Optional contribution step

    Enable outcome contribution

    Turn on outcome contribution from your coding-agent plugin when you are ready to share anonymized routing results.

    /hokusai:privacy reporting on
  2. 2Optional contribution step

    Report the latest route outcome

    Submit against the latest Hokusai route. The plugin previews the anonymized payload first and sends only after approval.

    /hokusai:report --use-latest --accepted --status succeeded --rating 4

Review / audit

Need to review what will be sent?

Use these local privacy commands to review routing records, preview stored metadata, or audit previous submission attempts.

/hokusai:privacy list
/hokusai:privacy preview <correlation-id>
/hokusai:privacy audit

Rewards context

What an integrator could earn

Route first. Then decide how to handle the token flow your harness creates.

Tasks / week

10,000

(projected)

Router lift

+3 DeltaOne

3 percentage points of cost-adjusted task success on the shared coding benchmark

Token Reward

750,000

Current Reward Value

~$19,986

(when fully vested)

Vested tokens can be held or redeemed for USDC at any time. Tokens vest 10% immediately and the remainder over a year. The bonding-curve valuation tracks paid router fees less infrastructure costs; if the router is adopted, fee volume grows, and the token's redemption value grows with it.

Router economicsContributor rewards

Pass through to users. OSS harness maintainers can pass 100% of token flow to the engineers whose tasks generate the data. Turns ownership into a user-acquisition feature.

Keep as revenue. Commercial harnesses can retain some or all of the token flow as a new revenue line that doesn't require a paywall.

Split. Mix the two. Configurable at integration; changeable later.

Need deeper docs?

Keep this page for setup. Go deeper after.

The setup flow lives above. Use these links when you need the economics notes, the reference harness, or the direct API surface.

Router economicsContributor rewardsReference implementationAdvanced @hokusai/core docsDirect API docs