Hecatoncheires

An AI-native, customizable project/case management platform with Slack integration.

Overview

Hecatoncheires is a flexible project and case management system that adapts to your workflow through configuration files. Define custom fields, integrate with Slack, and leverage AI for knowledge extraction and analysis.

Key Features

• Customizable Fields: Define project-specific fields via TOML configuration
• AI-Powered: Automatic knowledge extraction from various sources (Notion, Slack, etc.)
• Slack Integration: Native Slack channel and message integration
• GraphQL API: Type-safe, flexible API for frontend and integrations
• Field Types: Support for text, numbers, dates, URLs, user references, and select fields with metadata

Quick Start

The fastest way to try Hecatoncheires locally (in-memory backend, no auth) is in docs/getting_started.md. In short:

1. Create a config.toml file with your field definitions (see Configuration and examples/config.toml)
2. Run the server with the memory backend:

   go run . serve --repository-backend=memory --config=config.toml --no-auth=U000000000 --addr=:8080

3. Access the web UI at http://localhost:8080

For a production deployment (Firestore, Cloud Storage, LLM provider, Slack credentials), see docs/deployment.md.

Documentation

Full documentation lives in docs/, organized by audience.

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
Eval Harness	Offline scenario-based evaluation of LLM workflows
Slack Integration	Slack App setup (OAuth, Events, Interactivity, Slash)
Integrations	Notion and GitHub
User Guide	End-user Slack workflows
Operations	Observability, runbook, backup
Developing	Architecture and contributor guide

Development

Prerequisites

• Go 1.21+
• Node.js 18+ (for frontend)
• Corepack-managed pnpm (see below; the version is pinned via the packageManager field in frontend/package.json)
• Google Cloud Firestore

pnpm via Corepack

This repo pins the pnpm version in frontend/package.json (packageManager field). Enable Corepack once on your machine and it will automatically install the right pnpm:

corepack enable

Do NOT install pnpm globally with npm install -g pnpm — that bypasses the pin and is the most common cause of the lockfile being unexpectedly rewritten when you run e2e or build commands.

If you intentionally want to update dependencies, run pnpm install inside frontend/ on its own and commit the resulting pnpm-lock.yaml change. Day-to-day commands (build, e2e, etc.) use --frozen-lockfile and will fail fast if the lockfile is out of sync rather than silently rewriting it.

Building

task build           # Build complete application (frontend + backend)
task graphql         # Generate GraphQL code from schema
task dev:frontend    # Run frontend development server

Testing

Unit Tests

Run Go unit tests:

go test ./...

E2E Tests

Hecatoncheires includes end-to-end tests using Playwright to verify the complete application workflow.

Prerequisites:

• Node.js 18+ and pnpm
• The backend server must be running with --repository-backend=memory for testing

Run E2E tests:

# Install dependencies (only when you want to update them)
cd frontend
pnpm install
pnpm run test:e2e

# Or use the task command from the project root. This runner installs with
# --frozen-lockfile and will refuse to silently rewrite pnpm-lock.yaml.
task test:e2e

Other E2E test commands:

# Run tests with UI mode (interactive)
task test:e2e:ui

# Run tests in headed mode (show browser)
task test:e2e:headed

# Run tests in debug mode
task test:e2e:debug

# Show test report
task test:e2e:report

Manual E2E test setup:

If you want to run tests manually with a running server:

1. Start the backend server in memory mode:

   go run . serve \
     --repository-backend=memory \
     --config=frontend/e2e/fixtures/config.test.toml \
     --no-auth=U000000000 \
     --addr=:8080

2. In another terminal, run the E2E tests:

   cd frontend
   BASE_URL=http://localhost:8080 pnpm run test:e2e

CI/CD Integration:

E2E tests run automatically on pull requests via GitHub Actions. Test results and screenshots are uploaded as artifacts when tests fail.