Benchmark results

Three runs per hrns on a benchmark task using GPT-6-Luna with medium reasoning.

All runs pass 130/130 tests. Quality gates cover Ruff lint, Ruff formatting, and Pyrefly type checking.

Counts and costs are totals across three runs. Model responses include tool-only responses and final answers. Tool calls count underlying attempts, including failures; Codex's 41 orchestration calls contain 56 underlying attempts. Costs are cache-aware API equivalents in USD using common Standard model pricing.

Skill loads: Codex 0/3, OpenCode 1/3, hrns 3/3. The loaded skill is incremental-implementation, with relevant selection and partial adherence.

hrns

Define an agent once. Run it in Python, open it in a terminal, or host it remotely.

hrns combines native Pydantic AI capabilities with policy-controlled sessions, an independent ACP terminal, and authenticated remote hosting. Agent behavior stays in ordinary Python; the terminal can also connect to standard ACP agents that do not use this runtime.

Start developing

Requires Python 3.11+, macOS or Linux, uv, and just.

just install
just check

The checked-in lockfile pins the tested upstream versions. just install also installs the prek Git hook, which runs just check before each commit without applying automatic fixes. To install the hook after a manual dependency sync, run uv run prek install.

Use a local agent with your model

The local developer agent is the default connection mode. Install the provider extra and set the API key for the provider you use:

uv sync --locked --extra client --extra runtime --extra openai
export DEEPSEEK_API_KEY='your-key'
uv run hrns

Press l to configure a provider and model, type /models in a session, or create hrns.local.toml in the project:

provider = "deepseek"
model = "deepseek-chat"
api_key_env = "DEEPSEEK_API_KEY"

uv run hrns starts a session in the current directory using that model. The bundled hrns.coder capability gives it file tools, content search, and a shell in that directory: reads are automatic, while writes, edits, and commands ask for approval first. hrns.ask_user lets the model ask structured multiple-choice questions in the terminal; disable it with [capabilities] ask_user = false for headless runs. hrns.todo gives the model a session-scoped plan and shows it in the Todos tab of the right drawer. Configuration uses pydantic-settings. See local setup for OpenAI-compatible endpoints, local inference, other Pydantic AI providers, and headless execution.

Useful slash commands include /connect (switch or add a target), /models (configure or select the local model), /effort (change reasoning effort live), /plugins (toggle, configure, or add plugins), /mcp (list MCP servers and their tools), /skills (browse Agent Skills), and /todo (open the session's plan). Typing / shows an inline filtered list. Type $ in the composer to find a skill and insert a $skill-name reference, which runs that skill for the message. The older /model and /capabilities names remain aliases.

Any independent ACP agent can still be launched explicitly:

uv run hrns connect --stdio -- /path/to/agent --acp

See client usage for headless execution, profiles, approvals and the bridge.

Serve agents in your FastAPI app

from fastapi import FastAPI
from hrns.runtime import SQLiteSessionStore
from hrns.server import AgentServer

app = FastAPI()
agents = AgentServer(store=SQLiteSessionStore("./sessions.sqlite3"))
agents.add_agent(definition)
agents.mount(app)

add_agent binds and validates the definition's resource requirements at registration; pass resources=, or a definition.bind(...) result, when a capability needs host values. Install the server extra, register your AgentDefinition objects, and run the app with Uvicorn. Connect using hrns connect --url http://127.0.0.1:8080 --agent AGENT_ID. PostgreSQL and optional FastAPI authentication dependencies use the same API. See server embedding and the runnable example.

Layout

hrns is one distribution with optional extras. Protocol and local settings ship by default; the runtime, terminal, and server dependencies are opt-in.

Install only what you need, for example pip install 'hrns[client]', pip install 'hrns[openai]', or pip install 'hrns[all]'.

The hrns.client module does not import Pydantic AI or installed agent plugins, and installing hrns[client] alone does not install the runtime. Local stdio agents run in a separate process. Network agents run inside an existing FastAPI application through AgentServer, sharing an explicit SQLite or PostgreSQL store.

Design essentials

• Upstream ACP execution: PydanticAIACPAgent owns prompts, streaming, approvals, cancellation, history, and transcript replay.
• Native composition: managed bindings contribute their complete Pydantic AI behavior—tools, instructions, hooks and settings—and are selected when a session is composed.
• Live model and effort: both use standard ACP configuration options and apply from the next request.
• Host-owned state: sessions pin their principal/deployment scope, retain history and metadata, and never silently retry an uncertain prompt.
• Explicit resources: workspace and provider bindings belong to the host. A local workspace is a path, not a sandbox.
• Standard ACP first: generic streaming content, tools and approvals work without project-specific extensions.

Checks and distribution builds

just check
just lint
just build
just fix

just check runs the checks and builds the package. just lint runs formatting, lint, and type checks; just build builds the package. just fix applies automatic formatting and lint fixes. CI exercises the same non-mutating checks on macOS/Linux and Python 3.11–3.13. A wheel and source distribution are written to dist/; optional dependencies are declared as extras.

External provider, sandbox and durability integrations need their upstream extras and credentials. See the coverage matrix for managed, locally verified and deployment-only distinctions.

Releasing

The version comes from the git tag via hatch-vcs, so there is no version string to edit. Publishing runs on release: create a GitHub release and .github/workflows/publish.yml builds the distribution, runs just check, verifies the tag, and uploads to PyPI.

git tag 0.1.0
git push origin 0.1.0
gh release create 0.1.0 --generate-notes

The tag must match the version hatch-vcs derives, so 0.1.0 publishes 0.1.0. A mismatched tag fails the build instead of uploading an unintended version, and a version that already exists on PyPI is rejected.

Uploads use PyPI Trusted Publishing, so no API token is stored in the repository. Before the first release, configure a publisher on PyPI for the hrns project with this repository's owner and name, workflow publish.yml, and environment pypi. Because hrns does not exist on PyPI yet, use the pending publisher form.

License

MIT. See LICENSE.