ForjioHuudisIdentityPlugipayPaymentsCatentioAgentsStorlaunchE-commerceFulkrumaFulfilmentRiplloMarketingLinkSnapShort URLsPawpadoGPU streaming
Catentio Docs
⌘K

Concepts

This page covers the building blocks of Catentio: what each object is, how they relate to each other, and the lifecycle they go through. Read this before going deep on any specific feature — the rest of the docs assume you know what an agent, a run, and a project are and how they differ.

The model

Workspace
  ├── Agents (named: cimi, tora, sai, ren, fumi, iro, …)
  │     └── Runs
  │           ├── Subtasks (when the run decomposes)
  │           └── Events  ←  outbox-projected, replayable
  ├── Projects
  │     ├── Tasks
  │     │     └── Subtasks
  │     ├── Attachments
  │     └── Artifacts
  ├── Tools         (per-agent, scoped capabilities)
  ├── Skills        (versioned playbooks, PR-flow)
  ├── Memory        (entries, OTP-gated mutations)
  ├── Heartbeats    (cron-like agent triggers)
  ├── Integrations  (BYO OpenAI / ElevenLabs / Google / GitHub …)
  ├── API keys
  └── Output destinations

Everything is scoped to a workspace. In v1 (single-user mode) there's one workspace tied to your Huudis identity. Cross-workspace queries don't exist.

Workspace

A workspace is the top-level tenancy boundary. In Catentio's two deployment topologies:

  • Internal mode (v1, what these docs are for): one workspace, one Huudis user (the one configured in HUUDIS_ALLOWED_USER_ID), runtime co-located with the control plane.
  • Public SaaS mode (future): one workspace per Huudis identity, each backed by a dedicated runtime VPS provisioned by the control plane.

A workspace owns its agents, runs, projects, memory, tools, skills, API keys, integrations, and output destinations. Identifier shape: ws_….

Agent

An agent is a named, configured Claude principal with a persona, a tool budget, and access to the runtime's primitives. The default roster includes:

  • cimi — Hachimi, the orchestrator persona; default for general work.
  • tora — the implementer; ships code.
  • sai, ren, fumi, iro — specialised personas (research, scene work, taste-learning pipelines).

Plus a long tail of project-specific agents. The full list is at Dashboard → Agents.

You invoke an agent with a message (and optional context). The runtime spins up a fresh Claude CLI session under that agent's identity and tool budget, and returns a run.

Run

A run is one invocation of one agent on one input. It's the durable record of:

  • The original message (prompt + attached context).
  • The agent's streaming output (rendered as markdown).
  • A subtask tree, if the agent decomposed via the task runner.
  • Token + dollar cost (per model, accumulated as the run progresses).
  • Outbox events (one per state transition; replayable).
  • Artifacts produced (files, screenshots, JSON payloads).

States: queued → running → succeeded | failed | cancelled. Identifier: run_….

A run cannot be retried (it's immutable); to re-do the work, invoke the agent again or use retry-subtask on a project's subtask.

Project

A project is a pipeline-driven workflow that strings multiple agents together with checkpoints between them. The canonical example is content production: idea → research (Fumi) → storyboard (Fumi, with approval) → scaffold → character setup (Sai) → per-scene pipeline (Sai) → summary.

A project has:

  • A template (defines the step sequence and which agent owns each step).
  • Tasks (one per high-level step; ordered).
  • Subtasks under each task (decomposition decided at planning time, with dynamic re-planning if a step emits a replan block).
  • Attempts per subtask (retry preserves history).
  • Artifacts — outputs that survive the project lifetime.
  • Events — same outbox pattern as runs, but at project granularity.

States: running, paused, succeeded, failed, abandoned. You can pause a project mid-flight (the current subtask completes, then the runner stops); resume continues from the next subtask. Identifier: proj_….

Tool

A tool is a typed capability an agent can call — HTTP fetch, file read/write, Discord post, browser automation, MCP-exposed primitives. Tools are scoped to agents (an agent has access to a budget of tools, not the global set) and live in the runtime, not the control plane.

The portal lets you list, get, create, update, and delete tools at Dashboard → Tools. Catentio uses a PR-flow for tool changes: the portal opens a pull request against the runtime repo with the proposed change, and you merge it manually.

Skill

A skill is a named, versioned playbook for a recurring task — "review a PR", "set up a new STIA student record", "draft a Notion roadmap entry". Skills live as markdown files at app/skills/<slug>/SKILL.md in the runtime, and the runtime exposes list_skills + load_skill tools so agents can pull them on demand.

Skills are also PR-flow: install one through the portal and Catentio opens a PR with the new skill folder. Identifier: the slug.

Memory

The memory layer is the runtime's RAG store — embedded conversation history, project notes, and structured taste entries. The portal lets you:

  • List entries with filters (agent, kind, date range).
  • View one entry's full payload.
  • Create entries directly (for seeding context).
  • Update or delete entries — OTP-gated, since memory mutations are load-bearing.

Memory mutations require an OTP. The first call returns 403 with an OTP challenge; you re-send with the OTP header to commit.

Heartbeat

A heartbeat is a cron-like trigger that invokes an agent on a schedule. Use heartbeats for daily summaries, periodic check-ins, scheduled scrapes — anything that needs an agent to run on its own, without you in the loop.

You configure heartbeats per-agent at Dashboard → Heartbeats, and the portal exposes both the schedule (cron expression) and the prompt template.

Other primitives

A handful of supporting primitives round out the model. They're documented in their own portal sections:

  • Integrations — BYO credentials for OpenAI, ElevenLabs, Google, GitHub, and Forjio-family products.
  • Output destinations — where code and file outputs from agent runs should be written (a GitHub repo, a Google Drive folder, an output bucket).
  • Feature flags — runtime-level kill switches for experimental behaviour.
  • API keys — static tokens for server-to-server callers.
  • Webhooks — outbound HTTP delivery of outbox events to your own endpoints.
  • Scheduled jobs — the runtime's own internal cron (janitor, cost-stats refresh, billing reconcile, archival).
  • Events — a flat projection of every outbox event across runs, projects, and agents.

Next