README
¶
Hecatoncheires
An AI-native case management platform that lives in Slack.
What is Hecatoncheires
Hecatoncheires tracks Cases — risk reviews, security assessments, hiring pipelines, or any other work item your team runs — inside Workspaces whose fields you define in a TOML file. Every Case is tied to Slack, either as its own channel or as a thread in a monitored channel, so the discussion stays where your team already works. An AI agent answers mentions in those conversations: it drafts new Cases, updates existing ones, and investigates using Slack, Notion, GitHub, Jira, and the web. The same data is available through a Web UI and a GraphQL API.
Features
-
Configurable workspaces and fields — define each workspace's custom fields (text, Markdown, number, select, user, date, URL, Case references), statuses, and Slack behavior in TOML. See Configuration.
-
Slack-native workflow — create Cases with a slash command, ask the bot to draft one by mentioning it, and run each Case in its own channel or in a thread. See the User Guide and Slack Integration.
-
AI agent with tools — the agent reads Slack, Notion, GitHub, Jira, the web, and the workspace's Knowledge while it works on a Case. See Agent Tools.
-
Integrations — connect Notion, GitHub, and Jira; each one is optional.
-
Agent Jobs — run an agent on a schedule or when a Case is created or closed. See Configuration → Job Definitions and User Guide → Automation.
-
Knowledge — record organization-specific knowledge (operating rules, past judgements, …) once, and let people and the agent find it again by semantic search. See User Guide → Knowledge.
-
Access control — private Cases visible only to their Slack channel members, and a per-workspace Rego policy that decides who may use a workspace. See Configuration → Authorization.
-
MCP endpoint — a read-only Model Context Protocol server for AI clients, authorized by Rego. See MCP Server.
-
BigQuery export — full-refresh each workspace's data into BigQuery for analysis. See BigQuery Export.
-
Eval harness — run scenario files through the agent workflows offline and grade the results. See Eval Harness.
Requirements
To try it locally, nothing outside your machine is needed:
| Tool | Version |
|---|---|
| Go | 1.26.9+ (the go directive in go.mod) |
| Node.js | 22.22+ |
| pnpm | through Corepack (corepack enable) |
A production deployment runs on Google Cloud:
| Service | Purpose |
|---|---|
| Firestore | Primary data store |
| Cloud Storage | Agent session history and traces |
| LLM provider | OpenAI, Anthropic Claude (direct or on Vertex AI), or Google Gemini on Vertex AI |
| Gemini embeddings on Vertex AI | Required whenever the AI features are enabled, whichever LLM provider you use |
| Slack App | Sign-in, Case channels and threads, and the agent's conversations |
See Deployment for the full setup.
Quick Start
Run it locally with the in-memory backend and no Slack App:
git clone https://github.com/m-mizutani/hecatoncheires.git
cd hecatoncheires
corepack enable
# Build the Web UI, which is embedded into the Go binary
cd frontend
pnpm install --frozen-lockfile
pnpm run build
cd ..
go run . serve \
--repository-backend=memory \
--config=examples/config.toml \
--no-auth=U000000000
Then open http://localhost:8080. Data is kept in memory and lost on restart. Getting Started explains each step and how to run the test suite.
Deployment
Container images are published to the GitHub Container Registry for every pushed commit, tagged with the full commit SHA. For example:
docker pull ghcr.io/m-mizutani/hecatoncheires:d57137a1a75c8bc5e3cae18354089fcb450f476a
Deployment covers choosing an image, building your own, and configuring Firestore, Cloud Storage, the LLM, and Slack.
Documentation
| Document | Description |
|---|---|
| Documentation index | Reading paths by audience |
| Concepts | Core concepts and glossary |
| Getting Started | Run locally in minutes |
| Deployment | Production deployment overview |
| Configuration | config.toml complete reference |
| CLI Reference | Subcommands, flags, and environment variables |
| Slack Integration | Slack App setup (OAuth, Events, Interactivity, Slash) |
| Integrations | Notion, GitHub, and Jira |
| Agent Tools | Tools the AI agent can call, and where each is available |
| User Guide | End-user workflows in Slack and the Web UI |
| Operations | Observability, runbook, backup |
| MCP Server | Read-only MCP endpoint and its Rego authorization |
| BigQuery Export | Exporting workspace data to BigQuery |
| Eval Harness | Offline scenario-based evaluation of LLM workflows |
| Developing | Architecture and contributor guide |
Contributing
See CONTRIBUTING.md for the development environment, tests, and the checks a pull request must pass.
License
Hecatoncheires is licensed under the Apache License 2.0.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
pkg
|
|
|
adapter/policy
Package policy adapts the opaq Rego engine to the interfaces.PolicyClient port.
|
Package policy adapts the opaq Rego engine to the interfaces.PolicyClient port. |
|
agent/agenttrace
Package agenttrace converts agentkit's effect requests and results into gollem's trace representation.
|
Package agenttrace converts agentkit's effect requests and results into gollem's trace representation. |
|
agent/budget
Package budget turns an operator-configured ceiling into the agentkit.Limiter a Strategy answers Limit with.
|
Package budget turns an operator-configured ceiling into the agentkit.Limiter a Strategy answers Limit with. |
|
agent/interaction
Package interaction defines a host-neutral port for soliciting input from a human user in the middle of an agent run.
|
Package interaction defines a host-neutral port for soliciting input from a human user in the middle of an agent run. |
|
agent/kernel
Package kernel assembles the agentkit Kernel this application runs its agents on: the tool factory, the observability middleware, and the typed view of the per-Process scope that both of them read.
|
Package kernel assembles the agentkit Kernel this application runs its agents on: the tool factory, the observability middleware, and the typed view of the per-Process scope that both of them read. |
|
agent/react
Package react is the tool-calling agent loop, written as an agentkit Strategy: generate, run the tool calls the model asked for, feed the results back, repeat until it answers without asking for a tool.
|
Package react is the tool-calling agent loop, written as an agentkit Strategy: generate, run the tool calls the model asked for, feed the results back, repeat until it answers without asking for a tool. |
|
agent/runtrace
Package runtrace persists a case-scoped agent run as JobRunLog + JobRunEvent records so the case agent page can list it and show its per-call timeline.
|
Package runtrace persists a case-scoped agent run as JobRunLog + JobRunEvent records so the case agent page can list it and show its per-call timeline. |
|
agent/slackfmt
Package slackfmt holds the one statement of how an agent must write text that is posted to Slack.
|
Package slackfmt holds the one statement of how an agent must write text that is posted to Slack. |
|
agent/tool/actionwriter
Package actionwriter exposes the action-mutation gollem tools available to event-driven Agent Jobs.
|
Package actionwriter exposes the action-mutation gollem tools available to event-driven Agent Jobs. |
|
agent/tool/casemulti
Package casemulti exposes a cross-case ("workspace-scoped") gollem tool set for agent turns that operate across many Cases in one workspace, rather than a single Case pinned at construction time (contrast pkg/agent/tool/casewriter and pkg/agent/tool/core, both of which are built with one fixed CaseID and never take a case identifier at call time).
|
Package casemulti exposes a cross-case ("workspace-scoped") gollem tool set for agent turns that operate across many Cases in one workspace, rather than a single Case pinned at construction time (contrast pkg/agent/tool/casewriter and pkg/agent/tool/core, both of which are built with one fixed CaseID and never take a case identifier at call time). |
|
agent/tool/casewriter
Package casewriter exposes the case-mutation gollem tools available to event-driven Agent Jobs and the case-bound mention agent.
|
Package casewriter exposes the case-mutation gollem tools available to event-driven Agent Jobs and the case-bound mention agent. |
|
agent/tool/core
Package core contains gollem tools that operate on the case's domain state — currently actions.
|
Package core contains gollem tools that operate on the case's domain state — currently actions. |
|
agent/tool/github
Package github provides a GitHub App-authenticated client and a set of gollem agent tools (search, get_issue, get_pull_request, get_file, list_commits) that the AI agent can call against GitHub.
|
Package github provides a GitHub App-authenticated client and a set of gollem agent tools (search, get_issue, get_pull_request, get_file, list_commits) that the AI agent can call against GitHub. |
|
agent/tool/jira
Package jira adapts a gollem.ToolSet (e.g.
|
Package jira adapts a gollem.ToolSet (e.g. |
|
agent/tool/knowledge
Package knowledge exposes the workspace-wide shared-knowledge gollem tools available to agents.
|
Package knowledge exposes the workspace-wide shared-knowledge gollem tools available to agents. |
|
agent/tool/memo
Package memo exposes the Case-scoped memo gollem tools available to agents running in a Case context.
|
Package memo exposes the Case-scoped memo gollem tools available to agents running in a Case context. |
|
agent/tool/notion
Package notiontool contains gollem tools that let the AI agent search Notion pages/databases and retrieve their content as Markdown via the Notion Markdown Content API (Notion-Version 2026-03-11).
|
Package notiontool contains gollem tools that let the AI agent search Notion pages/databases and retrieve their content as Markdown via the Notion Markdown Content API (Notion-Version 2026-03-11). |
|
agent/tool/slack
Package slacktool contains gollem tools that let the AI agent interact with Slack: workspace-wide message search, bulk message fetch, and posting to a case channel.
|
Package slacktool contains gollem tools that let the AI agent interact with Slack: workspace-wide message search, bulk message fetch, and posting to a case channel. |
|
agent/tool/slackpost
Package slackpost exposes the Slack-posting gollem tool available to event-driven Agent Jobs.
|
Package slackpost exposes the Slack-posting gollem tool available to event-driven Agent Jobs. |
|
agent/tool/wsmeta
Package wsmeta exposes read-only tools that report on the WorkspaceRegistry — the registered workspaces, their custom field schemas, and their configured external sources.
|
Package wsmeta exposes read-only tools that report on the WorkspaceRegistry — the registered workspaces, their custom field schemas, and their configured external sources. |
|
agent/toolargs
Package toolargs repairs the one argument mistake a model cannot repair by itself: sending a single value where the tool spec declares an array.
|
Package toolargs repairs the one argument mistake a model cannot repair by itself: sending a single value where the tool spec declares an array. |
|
cli
Job runtime wiring shared between `hecatoncheires serve` (which hosts the Case lifecycle publisher) and `hecatoncheires scheduled` (which fires only the time-driven sweep).
|
Job runtime wiring shared between `hecatoncheires serve` (which hosts the Case lifecycle publisher) and `hecatoncheires scheduled` (which fires only the time-driven sweep). |
|
domain/model/authz
Package authz holds the Rego input/output document shapes used to authenticate and authorize MCP requests, plus the context plumbing that carries per-request HTTP metadata from the controller middleware down to the point where a tool call is evaluated against the policy.
|
Package authz holds the Rego input/output document shapes used to authenticate and authorize MCP requests, plus the context plumbing that carries per-request HTTP metadata from the controller middleware down to the point where a tool call is evaluated against the policy. |
|
domain/semantic
Package semantic is the catalog of text-field semantics.
|
Package semantic is the catalog of text-field semantics. |
|
domain/semantic/definition
Package definition declares the contract every semantic implements.
|
Package definition declares the contract every semantic implements. |
|
domain/semantic/slackchannelid
Package slackchannelid implements the slack_channel_id semantic: a text value that is the ID of a Slack channel.
|
Package slackchannelid implements the slack_channel_id semantic: a text value that is the ID of a Slack channel. |
|
repository/agentarchive
Package agentarchive provides Cloud Storage and in-memory implementations of gollem.HistoryRepository and gollem/trace.Repository for the AgentSession flow.
|
Package agentarchive provides Cloud Storage and in-memory implementations of gollem.HistoryRepository and gollem/trace.Repository for the AgentSession flow. |
|
repository/agentproc
Package agentproc implements agentkit.Repository on Firestore.
|
Package agentproc implements agentkit.Repository on Firestore. |
|
service/bqexport
Package bqexport is the BigQuery implementation of export.Sink (an external-system adapter, hence pkg/service).
|
Package bqexport is the BigQuery implementation of export.Sink (an external-system adapter, hence pkg/service). |
|
usecase/agent
Package agent contains the Slack-independent pieces shared by the agent hosts (`casebound`, `threadcase`, `proposal`, `wsagent`, `job`): the toolset resolver every host builds its sub-agent tools from, and the LLM call counter the plan-execute runtime reports through.
|
Package agent contains the Slack-independent pieces shared by the agent hosts (`casebound`, `threadcase`, `proposal`, `wsagent`, `job`): the toolset resolver every host builds its sub-agent tools from, and the LLM call counter the plan-execute runtime reports through. |
|
usecase/agent/casebound
Package casebound hosts the case-channel agent: a Slack mention in the channel of a channel-mode Case.
|
Package casebound hosts the case-channel agent: a Slack mention in the channel of a channel-mode Case. |
|
usecase/agent/job
Package job is the event-driven Agent Job runtime.
|
Package job is the event-driven Agent Job runtime. |
|
usecase/agent/planexec
Package planexec hosts the reusable plan-and-execute loop shared by the proposal (case-draft) host and the planexec-strategy Job host.
|
Package planexec hosts the reusable plan-and-execute loop shared by the proposal (case-draft) host and the planexec-strategy Job host. |
|
usecase/agent/threadcase
Package threadcase hosts the thread-mode agent: a plan-and-execute turn (planexec.Runner) that runs when a Case is created from a monitored channel post (materialize the Case fields) or when the bot is mentioned in a Case thread (investigate and respond / update fields / close).
|
Package threadcase hosts the thread-mode agent: a plan-and-execute turn (planexec.Runner) that runs when a Case is created from a monitored channel post (materialize the Case fields) or when the bot is mentioned in a Case thread (investigate and respond / update fields / close). |
|
usecase/agent/wsagent
Package wsagent hosts the workspace-channel agent: the plan-and-execute agent that runs when the bot is mentioned in a channel-mode workspace's configured workspace channel ([slack] workspace_channel).
|
Package wsagent hosts the workspace-channel agent: the plan-and-execute agent that runs when the bot is mentioned in a channel-mode workspace's configured workspace channel ([slack] workspace_channel). |
|
usecase/diagnosis
Package diagnosis hosts data-repair and inspection routines that operate across the persistent state owned by the rest of the application.
|
Package diagnosis hosts data-repair and inspection routines that operate across the persistent state owned by the rest of the application. |
|
usecase/eval
Package eval is the entry point of the offline eval harness: it loads scenario files, validates them (dry-run), runs each through its workflow driver, judges the produced artifact against the scenario checklist, dumps diagnostics for failing scenarios, and renders the aggregated report.
|
Package eval is the entry point of the offline eval harness: it loads scenario files, validates them (dry-run), runs each through its workflow driver, judges the produced artifact against the scenario checklist, dumps diagnostics for failing scenarios, and renders the aggregated report. |
|
usecase/eval/driver
Package driver runs a workflow type for one scenario against a prepared env and returns the artifact to judge.
|
Package driver runs a workflow type for one scenario against a prepared env and returns the artifact to judge. |
|
usecase/eval/env
Package env builds the in-memory environment a scenario runs against: a memory repository (seeded with the scenario's prior cases), in-memory history and trace repositories, the system-under-test wired via usecase.New, a recording fake Slack service, and per-tool clients that are either simulated (ToolSimulator) or live (recorded).
|
Package env builds the in-memory environment a scenario runs against: a memory repository (seeded with the scenario's prior cases), in-memory history and trace repositories, the system-under-test wired via usecase.New, a recording fake Slack service, and per-tool clients that are either simulated (ToolSimulator) or live (recorded). |
|
usecase/eval/evaltype
Package evaltype holds the shared value types and small interfaces of the eval harness.
|
Package evaltype holds the shared value types and small interfaces of the eval harness. |
|
usecase/eval/judge
Package judge evaluates a produced artifact against a scenario's checklist.
|
Package judge evaluates a produced artifact against a scenario's checklist. |
|
usecase/eval/llmrun
Package llmrun provides the gollem-backed implementation of evaltype.Completer.
|
Package llmrun provides the gollem-backed implementation of evaltype.Completer. |
|
usecase/eval/report
Package report aggregates scenario results and renders them: a human-readable stdout summary, a machine-readable JSON file, and per-scenario diagnostic dumps (see dump.go).
|
Package report aggregates scenario results and renders them: a human-readable stdout summary, a machine-readable JSON file, and per-scenario diagnostic dumps (see dump.go). |
|
usecase/eval/scenario
Package scenario defines the TOML schema for eval scenarios and loads / validates them.
|
Package scenario defines the TOML schema for eval scenarios and loads / validates them. |
|
usecase/eval/toolsim
Package toolsim provides simulated implementations of the agent's tool client interfaces.
|
Package toolsim provides simulated implementations of the agent's tool client interfaces. |
|
usecase/eval/usersim
Package usersim implements evaltype.Simulator: a simulated end-user that answers the agent's clarification questions, drawing on the scenario persona (who they are + what they know).
|
Package usersim implements evaltype.Simulator: a simulated end-user that answers the agent's clarification questions, drawing on the scenario persona (who they are + what they know). |
|
usecase/export
Package export implements the `export` subcommand's core: reading the current state of every configured workspace out of the repository and writing it, one table per entity, to a pluggable Sink (BigQuery today).
|
Package export implements the `export` subcommand's core: reading the current state of every configured workspace out of the repository and writing it, one table per entity, to a pluggable Sink (BigQuery today). |
|
usecase/job
Package job hosts the event-driven Agent Job lifecycle: a usecase that publishes Events, matches them to workspace Jobs, and dispatches the Job runtime in a background goroutine.
|
Package job hosts the event-driven Agent Job lifecycle: a usecase that publishes Events, matches them to workspace Jobs, and dispatches the Job runtime in a background goroutine. |
|
utils/errutil
Package errutil owns the project's non-fatal error reporting path.
|
Package errutil owns the project's non-fatal error reporting path. |
|
utils/pricing
Package pricing turns a model's token counts into money.
|
Package pricing turns a model's token counts into money. |
|
utils/slackid
Package slackid normalises Slack user identifiers across the codebase.
|
Package slackid normalises Slack user identifiers across the codebase. |
|
utils/uierr
Package uierr carries user-facing error classification on a goerr error and renders it into the fixed 3-part Slack message every failure surfaces:
|
Package uierr carries user-facing error classification on a goerr error and renders it into the fixed 3-part Slack message every failure surfaces: |
Click to show internal directories.
Click to hide internal directories.