SDK
Client & configuration
Construct a Harnext client, configure its behavior, and override settings per call.
Constructing a client
from harnext import Harnext
agent = Harnext(
provider="anthropic",
model="claude-opus-4-8",
api_key=None, # falls back to ANTHROPIC_API_KEY
cwd="./my-repo",
tools=["read", "write", "edit", "bash", "skill", "mcp"],
permission_mode="auto",
max_turns=40,
max_retries=3,
timeout=600,
system_prompt=None,
metadata={"team": "payments"},
)Options
Names are shown in Python snake_case; the TypeScript equivalent is the camelCase form.
providerstrrequiredmodelstroptionaldefault: provider defaultThe model id to use, e.g.
claude-opus-4-8. Defaults to the provider's recommended model.api_keystr | Noneoptionaldefault: envProvider key. When omitted, read from the provider's standard env var (e.g.
ANTHROPIC_API_KEY).cwdstr | Pathoptionaldefault: "."Working directory for file and shell tools. The agent cannot read or write outside this root unless a tool explicitly allows it.
toolslist[str | Tool]optionaldefault: all built-insWhich tools to enable. Pass built-in names, custom tools, or both.
permission_modestroptionaldefault: "auto"How tool calls are approved:
auto, manual, plan, or yolo. See below.max_turnsintoptionaldefault: 40Maximum agent loop iterations before stopping with
MaxTurnsExceeded.max_retriesintoptionaldefault: 3Retries for transient provider errors (rate limits, 5xx) with exponential backoff.
timeoutintoptionaldefault: 600Per-request timeout. Seconds in Python, milliseconds in TypeScript.
system_promptstr | Noneoptionaldefault: built-inOverride or extend the agent's system prompt. Pass a string to replace it, or use
append_system_prompt to add to it.sessionstr | Session | Noneoptionaldefault: newResume an existing session by id, or pass a
Session object. Omit to start fresh. See Sessions.skillslist[str]optionaldefault: []Skills to load — see Skills.
mcp_serversdictoptionaldefault: {}MCP servers to connect — see MCP servers.
on_permissioncallable | Noneoptionaldefault: NoneCallback to allow/deny tool calls in
manual mode.metadatadictoptionaldefault: {}Arbitrary key/values attached to the session for your own bookkeeping.
Permission modes
Permission mode controls how the agent is allowed to run tools that touch your machine.
auto— read-only tools run freely; writes and shell commands run unless youron_permissioncallback denies them. The default.manual— every side-effecting tool call is routed toon_permissionfor an explicit allow/deny.plan— the agent may read and reason but cannot write, edit, or run shell. Useful for dry runs and review.yolo— approve everything without prompting. Only for sandboxed or CI environments you fully trust.
def gate(req):
if req.tool == "bash" and "rm -rf" in req.command:
return "deny"
return "allow"
agent = Harnext(
provider="anthropic",
permission_mode="manual",
on_permission=gate,
)Per-call overrides
Most options can be overridden for a single call, or use with() / with_options() to derive a new client without mutating the original.
# Override just for this run
agent.run("Summarize the repo", provider="ollama", model="llama3.2")
# Derive a reusable variant
planner = agent.with_options(permission_mode="plan")Configuration file
Both SDKs and the CLI read an optional harnext.config.json (or harnext.toml) from the working directory. Explicit constructor options always win over the file, which wins over environment variables.
harnext.config.json
{
"provider": "anthropic",
"model": "claude-opus-4-8",
"permissionMode": "auto",
"tools": ["read", "write", "edit", "bash", "skill", "mcp"],
"mcpServers": {
"github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] }
}
}Resolution order
constructor options → harnext.config.json → environment variables (HARNEXT_* and provider keys) → built-in defaults.