Hayate Agent

A persistent AI agent for your terminal and messaging gateways. Use it to work on code interactively, or keep it running to handle conversations, scheduled tasks and longer-term goals.

Hayate Agent owns scheduling, queues and message delivery. PI is the current model and tool runtime; you do not need a separate PI installation to install Hayate Agent. Existing PI provider configuration can be reused.

Naming and compatibility

Hayate Agent uses npm package and executable hayate-agent, home ~/.hayate-agent, configuration hayate-agent.yaml and HAYATE_AGENT_* environment variables. Existing local agent state is read without moving it; see configuration. Internal repository/image names are exempt. “Harness” describes runtime architecture, not a second product name. The remaining audit is tracked in the naming inventory.

Branding does not replace configured agent keys, SOUL/VOICE identities or other agents' personas. Updated templates apply only to newly created files; existing files are never overwritten. Updating source or building does not activate a running installation: install the reviewed version and restart through your normal deployment process. Cross-repository overlays/plugins may retain their own display text until separately updated.

Repositories

• hayate-agent/core — product source and documentation.
• hayate-agent/plugins — independently versioned plugin adapters.
• hayate-agent/deployments — reserved deployment repository; no public deployment manifests are available there.

These are the canonical repository addresses, not a migration of existing runtime remotes, plugin source pins or deployment configuration. The deployments address does not establish a directory layout or a mapping from older overlay/base repositories. Core and Plugins publish source on GitHub. Core's public deploy/kubernetes/ contains only a SOUL.md persona example, not Kubernetes manifests or a complete configuration bundle. Use the native or Compose instructions below; Kubernetes requires operator-owned manifests. Existing installations do not need their remotes or configuration changed.

Install and start

You need Git and Node.js with npm. Node 24.22.1 LTS is recommended; the native CLI requires at least Node 22.19.0. Linux, macOS and Windows through WSL2 are supported.

git clone https://github.com/hayate-agent/core.git "$HOME/hayate-agent"
cd "$HOME/hayate-agent"
npm ci
npm install --global --prefix "$HOME/.local" .
export PATH="$HOME/.local/bin:$PATH"

cd /path/to/your/project
hayate-agent

Keep the checkout: this local installation links to it. Add the PATH line to your shell profile to make the command available in future terminals. No sudo or initialization wizard is required. npm ci also builds the CLI.

In the terminal interface, use /login to connect a supported provider and /model to select a model. Custom providers use PI's models.json; see configuration. Existing PI settings in ~/.pi/agent are reused, so changes there can affect other PI-based applications.

Your first session: ask the agent to inspect your project, use /help to browse commands, and /sessions or /resume to return to an earlier conversation. Each interactive launch starts a fresh conversation scoped to the current workspace.

For Docker Compose, Kubernetes and background services, see installation. Native Windows outside WSL2 is not supported.

What you can do

Capability	What it means in practice
Interactive coding	A fullscreen terminal interface with streaming answers, tool activity and a fixed input area. Configure which tools the model may use.
Persistent conversations	Keep history across restarts, name sessions, and explicitly resume work. Native PI session storage is the default.
Always-on work	Run heartbeats, recurring loops, cron jobs and standing goals without keeping a terminal open.
Parallel conversations	Separate conversations can run concurrently; each conversation processes its own queue in order.
Matrix gateway	Talk to the same Hayate Agent through DMs or rooms, with allowlists, mention rules, threads and approval handling.
HTTP run API	Submit runs programmatically and stream progress through a Hermes-compatible API. AgentOS integration is optional.
Identity and skills	Use SOUL.md for identity, VOICE.md for tone, and discoverable skills for reusable procedures.
Trusted plugins	Add commands, channels, tools, terminal panels and interactive dialogs through local ESM modules. Storage and manual compaction also have extension points.
Optional MCP	Enable PI-backed MCP integration when needed; it is not a required service.

Approvals are off by default. You can enable manual approval for selected tools. Plugins are trusted process code, not sandboxed extensions.

Everyday commands

• Sessions: /new, /title, /sessions, /resume, /compact.
• While working: /stop, /queue, /steer, /busy.
• Ongoing tasks: /goal, /heartbeat, /loop, /cron. See Cron reports for internal/user audiences and retained follow-through.
• Configuration: /model, /reasoning, /personality, /skills.
• Discoverability: /help, /status, /harness (bundled development guide).

Not every command is available on every channel. Use /help in your current interface rather than memorizing the full command list.

Run as a gateway

hayate-agent run

This starts the same Hayate Agent without the interactive TUI. Configure Matrix with MATRIX_HOMESERVER and either MATRIX_ACCESS_TOKEN or password-login settings. Set MATRIX_ALLOWED_USERS and the room/approval policy before connecting it to other people. A configured model provider is required to answer messages.

The HTTP API is enabled with API_SERVER_KEY; supply secrets through your runtime environment, not source control. Use a supervisor or container deployment for an always-on service. /restart drains work and exits with status 75; the supervisor is responsible for starting it again.

See configuration for settings and operations for durable delivery, retries, memory pressure and shutdown behavior.

Configuration and data

Hayate Agent state defaults to ~/.hayate-agent. Use HAYATE_AGENT_HOME for a separate agent home. A minimal optional hayate-agent.yaml looks like this:

agent: example-agent
timezone: Europe/Berlin
loop:
  busyMode: queue
  drainSeconds: 60

Model/provider credentials and PI settings live separately in ~/.pi/agent (or PI_CODING_AGENT_DIR). Persistent installations need to retain both locations. init creates missing starter files; doctor checks local configuration. Neither is required for normal interactive use.

The container runs as UID/GID 1000 and includes Chromium runtime libraries, Python virtual environments and native build tools. Agents can install their own CLI tools in writable persistent storage; no particular browser CLI is required. See browser tooling. For operator-owned Kubernetes deployments, pin immutable image digests and supply private configuration and secrets separately.

Current boundaries

• Native Matrix E2EE uses the Rust SDK with an identity-bound persistent store; see configuration, limits and acceptance. This capability requires the matching published crypto-enabled plugin pin and runtime image; older releases, including v0.1.129, do not support encrypted conversations.
• Slack and Telegram adapters are not included. The plugin channel interface supports additional transports, but does not implement them automatically.
• A Web UI and automatic activation/rollback of agent-built runtime versions are not shipped features.
• Matrix supports optional gateway progress and status reactions, with global defaults and per-gateway overrides. A generic secret-manager context is still under development.
• Durable queues reduce lost work, but crash recovery is at least once, not exactly once. External tool effects may be repeated after a crash.

Documentation

• Installation — native, Compose and Kubernetes
• Configuration — models, tools, identity and access settings
• Sessions — resume, storage providers and compaction
• MCP · Plugins — integrations and extension APIs
• Operations — recovery and service operation
• Self-development · Development guide

Contribute

Use a user-owned checkout, make changes on a feature branch, and run:

npm ci
npm run typecheck
npm test
npm run build

Submit changes through a pull request. Keep deployment identities, internal endpoints and credentials out of the public repository.

License

Apache License 2.0. See LICENSE.