Build on AFH.

Overview

While AFH is open it serves an API on 127.0.0.1 — the same one its own window uses. Anything you can do in the app you can do from code: create threads, send messages, read replies and diffs, set goals and to-do lists, approve actions, and schedule recurring jobs.

The app also serves an interactive reference generated from your exact version: Settings → Developer → Interactive reference (it opens /api/docs).

Quick start

1. Create a key. In AFH open Settings → Developer and click Create key. Copy it — it's shown only once.
2. Save it as an environment variable so it stays out of your code:

   setx AFH_API_KEY "afh_your_key_here"

3. Run a task. AFH must be open. The SDK finds it on its own.

from afh_sdk import AFH

afh = AFH()  # finds the running app, reads AFH_API_KEY
result = afh.run("Add a /health endpoint with a test, then run the tests",
                 directory=r"C:\code\my-api")
print(result["reply"])
print(result["todos"], result["cost"])

import { AFH } from "./afh.mjs";

const afh = await AFH.connect(); // finds the running app, reads AFH_API_KEY
const result = await afh.run("Add a /health endpoint with a test, then run the tests", {
  directory: "C:/code/my-api",
});
console.log(result.reply);

curl -s http://127.0.0.1:PORT/api/v1/run \
  -H "Authorization: Bearer $AFH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Add a /health endpoint with a test", "directory": "C:/code/my-api"}'

Authentication

Send your key in the Authorization header of every request:

Authorization: Bearer afh_3kX9…

• Keys start with afh_. AFH keeps only a SHA-256 hash in ~/.afh/api-keys.json, so a lost key can't be shown again — create a new one.
• Settings → Developer lists each key with when it was last used. Deleting a key stops it working immediately.
• API keys work on the local address only. Phones and other computers use Remote control, which has its own password.
• A key can do anything the app can, including running commands in your projects. Treat it like a password.

Finding the app

AFH picks a free port each time it starts and writes where it is to a discovery file while it runs:

{
  "url": "http://127.0.0.1:53817",
  "version": "1.8.7",
  "pid": 18244,
  "started": 1793270000000
}

The SDKs read it for you. To always use the same address instead, set a Fixed port in Settings → Developer, or pass url / set AFH_URL. If you moved AFH's data folder with AFH_HOME, the file is there instead.

Errors

Failed requests answer with a JSON body {"error": "message"} and a status code:

The SDKs raise AFHError with status and the message.

Run a task

The one-call way: start a thread in a folder (or continue one), send the prompt, and wait until the agent is done — including any autopilot turns toward a goal.

{
  "sessionID": "ses_01J…",
  "done": true,
  "reply": "Added GET /health returning {\"ok\": true} and tests/test_health.py. All 42 tests pass.",
  "todos": [{"content": "Add the route", "status": "completed"}, …],
  "goal": null,
  "cost": 0.0412,
  "title": "Add /health endpoint"
}

For runs started with wait: false: {sessionID, running, reply} — the newest answer so far.

Threads

A thread (session) is one conversation in one project folder, with its messages, to-do list, goal and undo history.

To-dos & goals

Changes & usage

Approvals

In build mode the agent asks before risky actions. You get a permission.asked event, or poll:

When the agent asks you questions, the request's action is question and metadata.questions holds them. Answer with {decision: "answer", answers: [{selected: ["label", …], other: "free text"}, …]} — one entry per question — or {decision: "dismiss"} to let it decide on its own.

Live events

A Server-Sent Events stream of everything happening in every thread — the same feed the app draws from. Each event is one data: line of JSON:

data: {"id":"evt_…","type":"session.text.delta","created":1793270001234,
       "data":{"sessionID":"ses_01J…","assistantMessageID":"msg_…","delta":"Adding the route"}}

A comment line (: ping) arrives every 15 seconds so idle connections stay open.

Scheduled jobs

Run a prompt in a project on a timetable — "every weekday at 9:00, update the dependencies and run the tests". Each run is a new thread you can read later. Jobs run while AFH is open; one that was due while it was closed runs once soon after it starts.

afh.save_schedule({
    "name": "Morning check",
    "directory": r"C:\code\my-api",
    "prompt": "Update outdated dependencies, run the tests, and fix anything that broke.",
    "every": "weekdays",
    "time": "09:00",
})

Models

{models, defaultModel, providerNames}. Each model has providerID, id, name, context, input (e.g. ["text", "image"]) and its prices. Pass "providerID/id" as model anywhere above.

Python SDK

One file, standard library only, Python 3.9+. Download afh_sdk.py next to your script.

From a terminal: python afh_sdk.py "Fix the failing test" C:\code\my-api

JavaScript SDK

One ES module for Node 18+ — no packages. Download afh.mjs.

Recipes

Stream a run as it happens

started = afh.run("Refactor utils.py into a package", directory=repo, wait=False)
for ev in afh.events(started["sessionID"]):
    if ev["type"] == "session.text.delta":
        print(ev["data"]["delta"], end="", flush=True)
    elif ev["type"] == "session.tool.input.started":
        print(f"\n→ {ev['data']['name']}")
    elif ev["type"].startswith("session.execution.") and ev["type"] != "session.execution.started":
        break

Review every commit before it lands

#!/usr/bin/env node
import { AFH } from "./afh.mjs";
const afh = await AFH.connect();
const out = await afh.run("Review the changes on this branch against main. Reply PASS or list the problems.",
  { directory: process.cwd(), mode: "plan", timeout: 600 });
console.log(out.reply);
process.exit(out.reply.trim().startsWith("PASS") ? 0 : 1);

Work toward a goal with autopilot

thread = afh.create_session(repo, title="Dark mode")
afh.set_goal(thread["id"], "Add a dark theme with a toggle in the header",
             criteria="Toggle works, choice persists, tests pass", start=True)
while afh.reply(thread["id"])["running"]:
    time.sleep(5)
print(afh.goal(thread["id"])["status"])