hecate

README

Agent operations console and local runtime control plane.
Run Hecate between operators, AI clients, agent runtimes, model providers, and local workspaces so agent work can be routed, supervised, approved, traced, and reviewable.

Status: public alpha. Hecate is useful today for model-provider routing, Hecate Chat, External Agent sessions, project-scoped work, approvals, artifacts, usage, and observability. It is not production-stable infrastructure yet: workflow runbooks, richer Agent Presets, browser QA, and sandbox hardening are still design or early-alpha work. Read known limitations before depending on it.

Contents

• What Hecate Is
• Positioning
• System Shape
• Current Capabilities
• Quick Start
• Use The Console
• Project, Context, And Memory Flow
• Architecture And Docs
• Status And Roadmap
• Contributing
• License

What Hecate Is

Hecate is the operator-facing runtime layer for AI work. It gives you one local place to talk to models, run Hecate-native agent tasks, supervise external agent CLIs, inspect project context, approve risky actions, collect evidence, and see what happened after the run.

Hecate is local-first in the operational sense: the runtime and UI run on your machine, Hecate-owned state is stored locally, and the gateway binds to loopback by default. It is not local-only: you can route to cloud providers and supervise external coding-agent CLIs that use their own accounts.

Hecate is not trying to be the only agent framework in your stack. It is the place where agents, agent frameworks, model calls, local tools, and project coordination become visible and controllable by the operator.

The short version:

• Gateway: one local API for OpenAI-compatible Chat Completions, Anthropic-shaped Messages, model discovery, failover, rate limits, provider health, and usage visibility.
• Console: a React operator UI for Chats, Connections, Tasks, Projects, Usage, Observability, and Settings.
• Native runtime: queued task runs, tool-calling agent_loop, approvals, per-call sandbox policy, artifacts, retries, resumes, and event streams.
• External Agent supervision: long-lived local ACP sessions for coding-agent CLIs, with readiness checks, approvals, adapter diagnostics, and Git diff review.
• Agent orchestration: project work, roles, assignments, handoffs, review artifacts, activity health, context snapshots, memory candidates, and operator-gated follow-up.
• Evidence: traces, route reports, task artifacts, diffs, logs, screenshots where available, and final run output close to the decision that produced it.

The product goal is not just to make model calls. It is to give the operator a single place to coordinate project-scoped agent work and understand what is happening, what context it used, what it changed, what it cost, what needs approval, and where the evidence lives.

Positioning

Hecate sits beside agent frameworks and agent CLIs rather than replacing all of them.

Question	Hecate answer
Is Hecate an agent?	It includes a native task agent loop, but Hecate itself is the operator console and runtime boundary around agent work, not a single autonomous persona.
Is Hecate an orchestrator?	Yes, when it coordinates projects, assignments, native tasks, external-agent sessions, approvals, handoffs, and reviews. The operator remains in control.
Is Hecate an agent framework?	Not primarily. Hecate exposes APIs and runtime contracts, but it does not require teams to rewrite their agents into a Hecate SDK.
Is Hecate a model gateway?	Yes, but the gateway is one subsystem. It exists so chats, tasks, external tools, and compatible clients share routing, policy, usage, and observability.
Is Hecate a project-management tool?	No. Projects are a coordination graph for AI work: context, assignments, evidence, memory candidates, reviews, handoffs, and runtime links.

The practical model is:

operator
  -> Hecate console / runtime control plane
    -> model gateway
    -> Hecate-native task agent loop
    -> supervised external agent CLIs
    -> portable project coordination state
    -> approvals, artifacts, traces, and review evidence

That makes Hecate useful whether the work is done by Hecate's own task runtime, an external coding-agent CLI, a local app using /v1, or a future agent system that claims project assignments through a portable coordination server.

System Shape

flowchart LR
    Operator["Operator"] --> Console["Browser / desktop console<br/>served by Hecate"]
    APIClients["Compatible API clients<br/>SDKs · tools · local apps"]

    subgraph HecateProcess["Local Hecate runtime process"]
        direction LR
        HTTP["Loopback HTTP server<br/>embedded UI assets<br/>/v1 · /hecate/v1"]
        Gateway["Model gateway<br/>routing · failover · usage"]
        TaskRuntime["Hecate task runtime<br/>queue · agent_loop<br/>retry/resume"]
        AgentSupervisor["External Agent supervisor<br/>ACP sessions · diagnostics"]
        State["Local state<br/>chats · tasks · settings<br/>runtime overlays"]
        Projects["Portable project coordination<br/>embedded Cairnline"]
        Evidence["Evidence + observability<br/>approvals · artifacts · events<br/>route reports · trace export"]

        HTTP --> Gateway
        HTTP --> TaskRuntime
        HTTP --> AgentSupervisor
        HTTP --> State
        HTTP --> Projects
        Gateway --> Evidence
        TaskRuntime --> Evidence
        AgentSupervisor --> Evidence
        Projects --> Evidence
        State --> Evidence
    end

    Providers["Cloud + local model providers"]
    Tools["Sandboxed workspace tools<br/>WorkspaceFS · ProcessRunner · GitRunner"]
    ExternalCLIs["External Agent CLIs / frameworks<br/>own accounts · own runtime"]

    Console --> HTTP
    APIClients --> HTTP
    Gateway --> Providers
    TaskRuntime --> Tools
    AgentSupervisor --> ExternalCLIs

The runtime is deliberately boring in the good way: request handling, routing, task execution, approvals, artifacts, and telemetry are all ordinary subsystems with memory, SQLite, and Postgres storage parity where persistence matters.

Current Capabilities

Surface	What works today
Model gateway	OpenAI-compatible Chat Completions, Anthropic-shaped Messages, streaming, vision, model discovery, provider health, failover, retry, usage events, and custom OpenAI-compatible endpoints.
Connections	Cloud presets plus Ollama, LM Studio, LocalAI, llama.cpp-compatible servers, local discovery, health checks, credentials, external-agent readiness, and durable approval grants.
Chats	Provider-routed dictation, direct model turns with image attachments, External Agent turns with arbitrary file inputs, tools-on task-backed turns, queued prompts, task/run/trace links, inline approvals, inline MCP Apps views, context packet snapshots, project-aware history, and workspace changes with rich per-file diffs.
Projects	Cairnline-backed project identity, roots, context and skill metadata, roles, work items, assignments, handoffs, project memory, review artifacts, and memory candidates, presented through Hecate's native operator cockpit and execution links.
Tasks	Native agent_loop runs, queue/lease execution, blocking approvals, streamed activity, artifacts, retry/resume, stale-run recovery, MCP tool/App integration, MCP probe, and MCP registry discovery.
External Agent	Supervised local ACP sessions for Codex, Claude Code, Cursor Agent, and Grok Build, including file inputs, readiness/version checks, prompt-first approvals, adapter diagnostics, cancellation, and Git diff inspect/revert. External agents keep their own accounts/billing.
Observability	OpenTelemetry traces/metrics/logs, response trace headers, local trace view, route reports, runtime stats, timing, token usage, and provider-reported cost where available.
Desktop app	Native bundles run the Hecate runtime as a sidecar. macOS Apple Silicon is launch-tested; Linux and Windows bundles are CI-built but still experimental.
Sandbox policy	WorkspaceFS boundaries, ProcessRunner/GitRunner seams, env sanitisation, output caps, timeouts, and bwrap / sandbox-exec wrappers where available. This is not container-level isolation.

Design direction that is not yet a runtime contract:

• Named workflow modes such as review, investigate, qa, ship, security-audit, and design-review.
• Browser-backed QA evidence and design review.
• Richer Agent Presets and preset workflows.
• Broader context-window management and external memory provider selection.
• A first-class workflow/runbook API if the v0 experiments prove valuable.

Quick Start

Choose the path that matches how you want to run Hecate.

Path	Best for
Desktop app	macOS personal use on your laptop with optional embedded workspace terminal support. No Docker required. Linux/Windows bundles are experimental.
Docker	Local container, scripted local deploys, and the safer Linux/Windows alpha path today.
From source	Contributors and local development.

Desktop app

Download the current alpha from hecate.sh or from the versioned GitHub Release assets below:

Platform	Bundle
macOS (Apple Silicon)	Hecate_0.4.0-alpha.1_aarch64.dmg
Linux x86_64	Hecate_0.4.0-alpha.1_amd64.deb or Hecate_0.4.0-alpha.1_amd64.AppImage
Windows x86_64	Hecate_0.4.0-alpha.1_x64_en-US.msi

Open the bundle and launch Hecate. The app starts the bundled runtime on a private loopback port, waits for it to become healthy, and opens the operator UI automatically. State lives in the platform data dir:

• macOS: ~/Library/Application Support/sh.hecate.app/
• Windows: %APPDATA%\sh.hecate.app\
• Linux: ~/.local/share/sh.hecate.app/

macOS release bundles are signed and notarized. Linux and Windows bundles are published by CI but have not yet had the same manual launch coverage. The desktop status, updater behavior, signing notes, and footguns live in Desktop app.

Docker

docker run --rm -p 127.0.0.1:8765:8765 -v hecate-data:/data \
  ghcr.io/hecatehq/hecate:0.4.0-alpha.1

Open http://127.0.0.1:8765.

The container intentionally publishes only on 127.0.0.1. If you bind it beyond loopback, put your own access control, firewall, or reverse proxy in front. See Security for the current threat model.

Pinned image tags, binary tarballs, checksums, compose examples, storage notes, and lost-token recovery live in Deployment.

From source

just dev

Local development requires Go, Bun, and the repo toolchain described in Development. First-run environment knobs live in .env.example.

Use The Console

Add a provider

On first boot, Chats is available immediately. If Hecate detects a local runtime such as Ollama or LM Studio, the first-run card can add it in one click. For manual setup, open Connections -> Add provider.

Cloud providers need an API key. Local providers need a running local server URL, usually the preset default. Custom OpenAI-compatible endpoints can be added from the same modal when the preset catalog is not enough.

After a provider is saved, Hecate discovers models and the Chats picker becomes routable. The full provider catalog, env bootstrapping, custom-endpoint walk-through, and credential rotation live in Providers.

Chat with or without tools

Hecate Chat keeps direct model turns and tools-on task-backed turns in one transcript. Tools off sends through the gateway. Tools on uses the task runtime with approvals, artifacts, sandbox policy, and traces.

If the selected model cannot call tools, Hecate keeps the chat usable as direct model chat and makes the tools-unavailable state visible.

With tools off, image-capable models accept PNG, JPEG, and WebP attachments by picker, drag-and-drop, or paste. Hecate stores the image body outside the transcript, loads its preview through the normal Hecate-native API path (including the runtime-token header when that optional guard is configured), and sends it only through an explicitly image-capable provider route. Image-bearing requests may retry on that exact provider generation but never fail over or follow a same-name replacement. Image drafts never enter the local busy-message queue, and the UI keeps submitted in-memory File values owned by their turn until it settles.

External Agent chats accept up to four non-empty files of any type, with the same 5 MiB per-file and 12 MiB per-message limits. Hecate resolves those inputs through the live ACP session: it uses supported inline image or embedded resource forms when available and otherwise supplies a private staged resource link. Transcript images keep their guarded previews; every other file stays inert until the operator chooses its explicit Download action. Malformed image-like inputs remain available to an External Agent as opaque files rather than becoming inline previews. Staged path aliases are removed from operator-visible output and approvals, and staged-turn raw ACP diagnostics are withheld when present.

The composer also supports dictation through an explicitly selected OpenAI, Groq, LocalAI, or env-configured OpenAI-compatible transcription route. Hecate records for at most two minutes, sends the bounded audio to that route only, does not retain the audio, and inserts the returned transcript at the cursor as an editable draft. Dictation never sends the chat message automatically.

Review workspace changes

Workspace changes sit beside the chat as session context. You can inspect the current Git diff, filter changed files, copy patches, and discard selected files without digging through transcript noise.

Supervise External Agents

External Agent sessions run through local ACP-compatible CLIs. Hecate supervises the session but does not proxy or pool those vendors' credentials.

Approvals surface as blocking operator prompts before gated actions can proceed.

See Chat sessions, Agent runtime, and External Agents for the deeper contracts.

Project, Context, And Memory Flow

The newer Hecate shape starts with projects. A project is the durable local identity for a work area: code, research, writing, design, ops, planning, or support. A project can start without a workspace; a workspace is the concrete filesystem root used later by a chat, task, or external-agent session when local files matter.

Hecate ships the operator cockpit and runtime integration for this flow. Cairnline, embedded in the current runtime, is the agent-neutral authority for durable project, work, memory, and evidence coordination. Hecate owns runtime launch, model routing, approvals, sandboxing, traces, External Agent supervision, context snapshots, and the richer operator UI. A separately installed Cairnline connector may replace the embedded package boundary later without changing the Projects experience.

flowchart LR
    Project["Project<br/>stable local identity"] --> Roots["Workspace roots"]
    Project --> Sources["Project sources<br/>URLs · notes · files · guidance"]
    Project --> Memory["Project memory<br/>operator-approved entries"]
    Project --> Work["Work items · assignments · handoffs"]

    Roots --> Session["Chat · task · external-agent session"]
    Sources --> Packet["Context packet snapshot"]
    Memory --> Packet
    Work --> Packet
    Session --> Packet
    Packet --> Call["Model or adapter call"]

    Session --> Artifacts["Artifacts · diffs · traces · reports"]
    Artifacts --> Candidates["Memory candidates"]
    Candidates --> Approval["Operator review"]
    Approval --> Memory

Important boundaries:

• Context packets snapshot what Hecate assembled for a call. They are audit evidence, not durable memory by themselves.
• Project memory is explicit operator-approved context. Hecate does not write memory automatically.
• Project sources are provenance and source metadata first; Hecate does not fetch source URLs or include source bodies unless a supported context policy path explicitly does so.
• Memory candidates can be proposed by chats, tasks, handoffs, or future workflows. They stay out of context until the operator promotes them.
• External-agent private memory stays outside Hecate unless the operator imports or writes Hecate memory explicitly.

Read the implemented contract in Runtime API, then the design records for Projects, Context assembly, Agent memory, and Workflow runbooks v0.

Architecture And Docs

The full docs index lives at docs/README.md. Start with the bucket that matches your job.

You are...	Start here
Running Hecate locally	Desktop app, Deployment, Security, Providers
Calling Hecate from a client	Runtime API, Chat sessions, Agent runtime, Events
Building coding-agent integrations	External Agents, MCP integration, Events
Changing the codebase	Architecture, Development, Release, docs-ai
Planning future runtime behavior	Design records, especially the proposal/accepted/candidate bucket before implementation starts.

Runtime references:

• Runtime API - Hecate-native endpoints, task lifecycle, approvals, streaming, projects, memory, work items, and handoffs.
• Agent runtime - agent_loop, tools, costs, retry-from-turn, stdout/stderr, and system prompt layers.
• Chat sessions - transcript segments, direct turns, task-backed turns, queued prompts, context packets, and External Agent chats.
• Events - run-event names, payloads, and SSE replay.
• Telemetry - OpenTelemetry spans, metrics, logs, trace headers, local trace view, and retention.
• Sandbox - subprocess boundaries, policy validation, env sanitisation, output caps, timeouts, and OS wrappers.

Operator guides:

• Providers - provider presets, custom endpoints, credentials, model discovery, health, and circuit breaking.
• Security - local-first threat model, workspace safety, approvals, secrets, and advisory handling.
• Known limitations - the plain-language alpha boundary.

Status And Roadmap

Hecate is public-alpha software. The fastest-moving areas are supervised agent execution, memory/context visibility, External Agent ergonomics, desktop packaging, workflow runbook experiments, and sandbox hardening.

Near-term design direction:

1. Keep embedded Cairnline as the portable Projects authority while Hecate evolves as the operator cockpit and runtime/orchestration layer.
2. Keep projects, context packets, memory, artifacts, approvals, and traces as the shared substrate for all agent work.
3. Add reversible runtime-wide writer quiescence before enabling in-process data reset; the reserved endpoint currently fails closed without deleting state.
4. Prototype one report-only qa workflow using existing task runs before adding a standalone workflow engine.
5. Start browser support with conservative evidence capture and explicit state isolation.
6. Promote successful workflow lessons only as memory candidates with provenance and operator approval.

The broader alpha-to-beta gate lives in Beta roadmap. Proposed, accepted, candidate, implemented, and parked design records live in Design records.

Contributing

See CONTRIBUTING.md. If you work with an AI assistant, start with AGENTS.md; the provider-neutral guidance layer lives in docs-ai.

License

MIT. See LICENSE.

Documentation

Overview

Package hecate is a thin module-root package whose only job is hosting the //go:embed directive for the built UI assets. Go's embed directive cannot reach paths above the source file's directory, so the embed has to live at the module root where ui/dist sits.

Index

• Variables
• func UISubFS() fs.FS

Variables

var UIDistFS embed.FS

UIDistFS holds the built UI bundle. The Makefile / CI runs `bun run build` before `go build`, which populates ui/dist with the real React app. When that hasn't happened, the embedded directory contains only the .gitkeep placeholder and consumers fall back to a friendly "UI not built" page.

Functions

func UISubFS

func UISubFS() fs.FS

UISubFS returns the embedded ui/dist subtree (or nil if the embed is somehow unreadable). Callers should treat nil as "UI not built" and serve a fallback page.