Get started

Quickstart

Build, run, and stream your first agent in under five minutes — then resume the session and inspect what it did.

Create a client

A client binds a provider and model to a working directory. The agent's file tools operate relative to cwd.

from harnext import Harnext

agent = Harnext(
    provider="anthropic",
    model="claude-opus-4-8",
    cwd="./my-repo",
)

Run a task

run() executes the full agent loop and resolves once the task is complete. The result carries the final message, the tool steps, token usage, and the files that changed.

result = agent.run("Add a /health route that returns 200 OK")

print(result.text)
print("changed:", result.files_changed)
print("tokens:", result.usage.total_tokens)

Stream the work live

Use stream() to observe the agent as it thinks and calls tools — ideal for CLIs, logs, and progress UIs.

for event in agent.stream("Refactor auth into its own module"):
    if event.type == "text":
        print(event.text, end="", flush=True)
    elif event.type == "tool_call":
        print(f"\n→ {event.tool}({event.args})")

Resume the session

Every run is saved. Re-open it by id to continue with full context — no need to repeat the history.

sid = result.session_id

follow_up = Harnext(provider="anthropic", session=sid)
follow_up.run("Now add tests for the new module")

Run it in one shot

Prefer the terminal? The same task runs from the CLI, and the SDK can read back the session it produces.

Shell

harnext -p "Add a /health route that returns 200 OK" --provider anthropic

Next steps

Continue with the SDK overview for the full client surface, or jump to Tools to give the agent custom capabilities.

Quickstart

Run it in one shot#

Run it in one shot