Skip to content

README.md

Latest commit

 

History

History
79 lines (62 loc) · 5.82 KB

README.md

File metadata and controls

79 lines (62 loc) · 5.82 KB

Hecate documentation

The project README is the product on-ramp. This directory is the reference shelf: how to run Hecate, integrate with it, observe it, and change it without tripping over alpha edges.

Start Here

Pick the path closest to what you are doing.

You are... Read in this order
Running Hecate locally Desktop app, Deployment, Security, Providers, Chat sessions, Known limitations
Calling Hecate from a client Runtime API, Chat sessions, Agent runtime, Events
Building or using coding-agent integrations External agent adapters, ACP bridge, Runtime API, Events, MCP integration
Changing the codebase Architecture, Development, Alpha-to-beta roadmap, docs-ai/, Release
Working as an AI agent AGENTS.md, docs-ai/README.md, then the relevant docs-ai/skills/*/SKILL.md

Operator Docs

Doc What it answers
Deployment Docker, binary install, image pinning, storage backends, rate limits, lost-token recovery.
Desktop app Native bundles, first-launch warnings, platform data dirs, sidecar lifecycle, roadmap.
Security Local-first threat model, runtime boundaries, workspace safety, approvals, secrets, and advisory handling.
Providers Built-in provider presets, OpenAI-compatible custom endpoints, credentials, model discovery, health, circuit breaking.
Chat sessions Hecate Chat transcript segments, tools on/off behavior, task-backed turns, queued prompts, approvals in Chats, and shared activity rendering.
Known limitations The honest alpha boundary: API/schema stability, sandbox limits, desktop gaps, deployment scope.

Runtime And Integration Docs

Doc What it answers
Runtime API /hecate/v1/tasks/*, /hecate/v1/agent-chat/*, approvals, run streaming, queue/lease semantics, health/discovery endpoints.
Agent runtime agent_loop configuration, built-in tools, stdout/stderr handling, system prompt layers, approvals, cost ceiling, retry-from-turn.
Events Implemented event names, payloads, stdout/stderr stream chunks, and when each is emitted. Use this for today's /hecate/v1/events consumers.
Chat sessions Conversation persistence model behind the Chats UI, Hecate Chat segments, provider/model switching, queued prompts, and external-agent sessions.
External agent adapters Hecate as an ACP client/operator: use Codex, Claude Code, and Cursor Agent from Chats; install checks, persistence, troubleshooting, current gaps.
MCP integration Hecate as an MCP server and external MCP servers as task tools.
ACP bridge Hecate as an ACP agent for editor panels. Host setup, gateway discovery, session model, smoke test, and current gaps.
Sandbox Per-call subprocess execution, policy validation, env sanitisation, output cap, timeout, and OS wrappers.

Observability Docs

Doc What it answers
Telemetry OpenTelemetry traces, metrics, logs, response headers, local trace view, runtime stats, retention.

Contributor Docs

Doc What it answers
Architecture Gateway flow, orchestrator responsibilities, task-runtime queue/lease model, agent turn cycle, storage tiers.
Development Go + Bun + just + Rust/Cargo setup, local dev, test ladder, screenshot tooling, package map.
Release Versioning, verification gate, release script, image build, recovery, release-note shape.
Alpha-to-beta roadmap Beta gate, core runtime work, view-by-view UX order, cleanup/refactoring, and branch/release workflow.
docs-ai/ Vendor-neutral agent guidance: workflow, verification, skills, task recipes.

Candidate Contracts

These are design contracts in progress. They are useful for review and for early frontend/client experiments, but they are not semver-backed API promises yet.

Doc Status
RFC index All candidate and experimental design contracts.
Agent event protocol v1 candidate Candidate envelope exists; payload schemas and stability guarantees are still in progress.
Agent event protocol experimental extensions Parking lot for future event groups such as thinking blocks, sub-agents, multimodal output, and branching.
Artifact storage v1 candidate Candidate shape for persisted command output, patches, fetched resources, and artifact retention.
External agent adapters candidate Candidate shape for chatting with Codex, Claude Code, Cursor Agent, and future coding-agent CLIs through Hecate.
Hecate Chat and model capabilities Accepted alpha direction for Hecate Chat tools on/off segments, model capability metadata, profiles, and future probes.

External Entry Points